{"openapi":"3.1.0","info":{"title":"Zelvyn API","summary":"Math. Data. Decisions.","description":"The **Zelvyn API** is a stateless calculation and analytics platform for\nmathematics, statistics and business metrics.\n\nEvery JSON response shares one envelope: successes return\n`{ success, data, meta }` and failures return `{ success, error, meta }`,\nwith a `meta.requestId` correlation id on both. Calculations are never\npersisted, and no database is on the calculation path.\n\n## Authentication is optional\n\nEndpoints are public. Send an API key via `Authorization: Bearer <key>` or\nthe `x-api-key` header to receive plan rate limits and monthly quota\naccounting. Keyless (anonymous) traffic is limited per hashed client IP and\nhas no account quota. See the *Authentication* section of the developer\ndocumentation for the full key lifecycle.\n\n## Conventions\n\n- All request bodies are JSON objects and are strictly validated: unknown\n  fields are rejected (`additionalProperties: false`).\n- Percentage metrics return **percent points** (`40` means 40%); `roas` is a\n  plain ratio (`4` means 4×).\n  Percentages are never fractions and never carry a `%` sign.\n  - Exact integer results beyond `Number.MAX_SAFE_INTEGER` are returned as\n    decimal strings (never rounded).\n- Every error is a JSON envelope; no HTML error pages are returned for API paths.","version":"0.1.0","license":{"name":"Proprietary"},"x-zelvyn-api-version":"v1"},"servers":[{"url":"https://api-zelvyn.devs.surf","description":"Production"},{"url":"http://localhost:3000","description":"Local development (`npm run dev`)"}],"security":[{},{"bearerAuth":[]},{"apiKeyAuth":[]}],"tags":[{"name":"Health","description":"Liveness and readiness."},{"name":"Statistics","description":"Descriptive statistics over numeric datasets (up to 10,000 values per request)."},{"name":"Math","description":"Mathematical foundation: 16 operations (decimal-exact arithmetic, powers/roots/logs, and exact integer combinatorics up to n = 1000)."},{"name":"Business Analytics","description":"Business metrics: 17 operations across profitability, advertising and customer unit economics. Percentage metrics return percent points; ROAS is a ratio."}],"paths":{"/api/v1/health":{"get":{"tags":["Health"],"summary":"Liveness / readiness probe","description":"Stateless liveness/readiness probe: no database, dependencies, or external calls. Use it to verify reachability and read the running service/API versions.","operationId":"getHealth","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"}],"responses":{"200":{"description":"Service is up.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HealthData"}}}]},"example":{"success":true,"data":{"status":"ok","service":"zelvyn-api","apiVersion":"v1","version":"0.1.0","environment":"production"},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"}}}},"/api/v1/statistics/mean":{"post":{"tags":["Statistics"],"summary":"Arithmetic mean","description":"Returns the arithmetic mean of `values` (Σ xᵢ / n). Uses Neumaier compensated summation, so datasets with widely varying magnitudes keep low-order digits. Accepts 1–10,000 finite numbers.","operationId":"statisticsMean","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatisticsMeanRequest"},"example":{"values":[10,20,30]}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/StatisticsMeanResult"}}}]},"example":{"success":true,"data":{"operation":"mean","result":20},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/math/add":{"post":{"tags":["Math"],"summary":"Add numbers","description":"Returns the sum of `values` (Σ valuesᵢ). Decimal-exact internally (40 significant digits), so `[0.1, 0.2]` returns `0.3`. Accepts 1–10,000 finite numbers; negatives and zero are allowed.","operationId":"mathAdd","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MathAddRequest"},"example":{"values":[0.1,0.2,0.3]}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MathAddResult"}}}]},"example":{"success":true,"data":{"operation":"add","result":0.6},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/math/subtract":{"post":{"tags":["Math"],"summary":"Subtract numbers (left to right)","description":"Returns `values₀ − values₁ − values₂ − …`, evaluated strictly left to right (the array is the expression). Requires at least two finite values.","operationId":"mathSubtract","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MathSubtractRequest"},"example":{"values":[10,3,4]}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MathSubtractResult"}}}]},"example":{"success":true,"data":{"operation":"subtract","result":3},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/math/multiply":{"post":{"tags":["Math"],"summary":"Multiply numbers","description":"Returns the product of `values` (Π valuesᵢ). Decimal-exact internally. Accepts 1–10,000 finite numbers.","operationId":"mathMultiply","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MathMultiplyRequest"},"example":{"values":[2,3,4]}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MathMultiplyResult"}}}]},"example":{"success":true,"data":{"operation":"multiply","result":24},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/math/divide":{"post":{"tags":["Math"],"summary":"Divide numbers (left to right)","description":"Returns `values₀ ÷ values₁ ÷ values₂ ÷ …`, evaluated strictly left to right. Requires at least 2 finite values. A zero divisor is a `DIVISION_BY_ZERO` domain error (HTTP 422), not a validation error.","operationId":"mathDivide","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MathDivideRequest"},"example":{"values":[100,4,5]}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MathDivideResult"}}}]},"example":{"success":true,"data":{"operation":"divide","result":5},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/math/percent-of":{"post":{"tags":["Math"],"summary":"Percent of a value","description":"Returns `(percentage / 100) × value`. Both inputs are finite numbers (negatives allowed).","operationId":"mathPercentOf","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MathPercentOfRequest"},"example":{"percentage":15,"value":240}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MathPercentOfResult"}}}]},"example":{"success":true,"data":{"operation":"percent-of","result":36},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/math/percentage-change":{"post":{"tags":["Math"],"summary":"Percentage change between two values","description":"Returns `((to − from) / from) × 100` as percent points (so `25` means +25%). The signed `from` value is the denominator. `from = 0` has no defined relative change and yields `DIVISION_BY_ZERO` (HTTP 422).","operationId":"mathPercentageChange","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MathPercentageChangeRequest"},"example":{"from":80,"to":100}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MathPercentageChangeResult"}}}]},"example":{"success":true,"data":{"operation":"percentage-change","result":25},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/math/power":{"post":{"tags":["Math"],"summary":"Raise a base to an exponent","description":"Returns `base^exponent`. `0^0 = 1` and `0^positive = 0` by convention; `0^negative` yields `DIVISION_BY_ZERO` (422); a negative base with a non-integer exponent yields `UNDEFINED_RESULT` (422); overflow/underflow yield `UNDEFINED_RESULT` (422).","operationId":"mathPower","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MathPowerRequest"},"example":{"base":2,"exponent":10}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MathPowerResult"}}}]},"example":{"success":true,"data":{"operation":"power","result":1024},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/math/sqrt":{"post":{"tags":["Math"],"summary":"Square root","description":"Returns the principal (non-negative) square root. A negative input has no real square root and yields `UNDEFINED_RESULT` (HTTP 422).","operationId":"mathSqrt","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MathSqrtRequest"},"example":{"value":144}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MathSqrtResult"}}}]},"example":{"success":true,"data":{"operation":"sqrt","result":12},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/math/nth-root":{"post":{"tags":["Math"],"summary":"N-th root","description":"Returns the principal real `degree`-th root of `value`. `degree` is an integer from 1 to 10,000. An even root of a negative value yields `UNDEFINED_RESULT` (422); odd roots of negatives return the negative real root.","operationId":"mathNthRoot","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MathNthRootRequest"},"example":{"value":27,"degree":3}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MathNthRootResult"}}}]},"example":{"success":true,"data":{"operation":"nth-root","result":3},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/math/log":{"post":{"tags":["Math"],"summary":"Logarithm to a base (default 10)","description":"Returns the logarithm of `value` to `base`. `base` is optional and defaults to 10. `value ≤ 0`, `base ≤ 0`, and `base = 1` yield `UNDEFINED_RESULT` (HTTP 422).","operationId":"mathLog","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MathLogRequest"},"example":{"value":1000}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MathLogResult"}}}]},"example":{"success":true,"data":{"operation":"log","result":3},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/math/ln":{"post":{"tags":["Math"],"summary":"Natural logarithm","description":"Returns the natural logarithm (base e). `value ≤ 0` yields `UNDEFINED_RESULT` (HTTP 422).","operationId":"mathLn","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MathLnRequest"},"example":{"value":1}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MathLnResult"}}}]},"example":{"success":true,"data":{"operation":"ln","result":0},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/math/factorial":{"post":{"tags":["Math"],"summary":"Factorial","description":"Returns `n!` for an integer n from 0 to 1,000 (`0! = 1`). Exact integer results beyond `Number.MAX_SAFE_INTEGER` are returned as decimal strings and are never rounded.","operationId":"mathFactorial","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MathFactorialRequest"},"example":{"n":5}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MathFactorialResult"}}}]},"example":{"success":true,"data":{"operation":"factorial","result":120},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/math/gcd":{"post":{"tags":["Math"],"summary":"Greatest common divisor","description":"Returns the greatest common divisor of two integers, sign-independently. `gcd(0, b) = |b|`; `gcd(0, 0)` yields `UNDEFINED_RESULT` (HTTP 422). Both inputs must be safe integers.","operationId":"mathGcd","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MathGcdRequest"},"example":{"a":12,"b":18}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MathGcdResult"}}}]},"example":{"success":true,"data":{"operation":"gcd","result":6},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/math/lcm":{"post":{"tags":["Math"],"summary":"Least common multiple","description":"Returns the least common multiple of two integers, sign-independently. `lcm(0, b) = 0`; `lcm(0, 0)` yields `UNDEFINED_RESULT` (HTTP 422). Both inputs must be safe integers.","operationId":"mathLcm","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MathLcmRequest"},"example":{"a":4,"b":6}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MathLcmResult"}}}]},"example":{"success":true,"data":{"operation":"lcm","result":12},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/math/permutations":{"post":{"tags":["Math"],"summary":"Permutations P(n, r)","description":"Returns the number of ordered selections `P(n, r) = n! / (n − r)!`. `n` and `r` are integers from 0 to 1,000 and the contract requires `r ≤ n`. Exact integer results beyond `Number.MAX_SAFE_INTEGER` are returned as decimal strings and are never rounded.","operationId":"mathPermutations","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MathPermutationsRequest"},"example":{"n":5,"r":2}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MathPermutationsResult"}}}]},"example":{"success":true,"data":{"operation":"permutations","result":20},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/math/combinations":{"post":{"tags":["Math"],"summary":"Combinations C(n, r)","description":"Returns the number of unordered selections `C(n, r) = n! / (r! (n − r)!)`. `n` and `r` are integers from 0 to 1,000 and the contract requires `r ≤ n`. Exact integer results beyond `Number.MAX_SAFE_INTEGER` are returned as decimal strings and are never rounded.","operationId":"mathCombinations","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MathCombinationsRequest"},"example":{"n":52,"r":5}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MathCombinationsResult"}}}]},"example":{"success":true,"data":{"operation":"combinations","result":2598960},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/business/profit":{"post":{"tags":["Business Analytics"],"summary":"Profit","description":"Returns `revenue − costs`. Monetary inputs are signed (negative results are meaningful losses).","operationId":"businessProfit","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessProfitRequest"},"example":{"revenue":1000,"costs":600}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessProfitResult"}}}]},"example":{"success":true,"data":{"operation":"profit","result":400},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/business/profit-margin":{"post":{"tags":["Business Analytics"],"summary":"Profit margin (percent)","description":"Returns `(revenue − costs) / revenue × 100` as percent points (`40` means 40%). `revenue = 0` yields `DIVISION_BY_ZERO` (HTTP 422).","operationId":"businessProfitMargin","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessProfitMarginRequest"},"example":{"revenue":1000,"costs":600}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessProfitMarginResult"}}}]},"example":{"success":true,"data":{"operation":"profit-margin","result":40},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/business/markup":{"post":{"tags":["Business Analytics"],"summary":"Markup (percent)","description":"Returns `(price − cost) / cost × 100` as percent points. `cost = 0` yields `DIVISION_BY_ZERO` (HTTP 422). Distinct from margin, which is based on revenue/price.","operationId":"businessMarkup","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessMarkupRequest"},"example":{"price":120,"cost":100}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessMarkupResult"}}}]},"example":{"success":true,"data":{"operation":"markup","result":20},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/business/roi":{"post":{"tags":["Business Analytics"],"summary":"Return on investment ROI (percent)","description":"Returns `profit / investment × 100` as percent points, where `profit` is the net gain. `investment = 0` yields `DIVISION_BY_ZERO` (HTTP 422). Distinct from ROAS, which is a revenue ratio.","operationId":"businessRoi","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessRoiRequest"},"example":{"profit":250,"investment":1000}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessRoiResult"}}}]},"example":{"success":true,"data":{"operation":"roi","result":25},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/business/roas":{"post":{"tags":["Business Analytics"],"summary":"Return on ad spend ROAS (ratio)","description":"Returns `revenue / adSpend` as a plain ratio (`4` means 4×). `adSpend = 0` yields `DIVISION_BY_ZERO` (HTTP 422). Unlike ROI, this is not multiplied by 100.","operationId":"businessRoas","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessRoasRequest"},"example":{"revenue":4000,"adSpend":1000}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessRoasResult"}}}]},"example":{"success":true,"data":{"operation":"roas","result":4},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/business/cagr":{"post":{"tags":["Business Analytics"],"summary":"Compound annual growth rate CAGR (percent)","description":"Returns `((endValue / beginValue)^(1 / periods) − 1) × 100` as percent points. `periods` must be greater than 0. `beginValue ≤ 0` or `endValue < 0` yields `UNDEFINED_RESULT` (HTTP 422); overflow yields `UNDEFINED_RESULT`; a total loss returns `−100`.","operationId":"businessCagr","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessCagrRequest"},"example":{"beginValue":100,"endValue":121,"periods":2}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessCagrResult"}}}]},"example":{"success":true,"data":{"operation":"cagr","result":10},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/business/break-even":{"post":{"tags":["Business Analytics"],"summary":"Break-even volume (units)","description":"Returns `fixedCosts / (price − variableCost)`, the number of units needed to cover fixed costs (may be fractional). A contribution of `price − variableCost ≤ 0` makes break-even unreachable and yields `UNDEFINED_RESULT` (HTTP 422).","operationId":"businessBreakEven","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessBreakEvenRequest"},"example":{"fixedCosts":1000,"price":20,"variableCost":12}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessBreakEvenResult"}}}]},"example":{"success":true,"data":{"operation":"break-even","result":125},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/business/conversion-rate":{"post":{"tags":["Business Analytics"],"summary":"Conversion rate (percent)","description":"Returns `conversions / sessions × 100` as percent points. Counts are non-negative. `sessions = 0` yields `DIVISION_BY_ZERO` (HTTP 422).","operationId":"businessConversionRate","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessConversionRateRequest"},"example":{"conversions":50,"sessions":1000}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessConversionRateResult"}}}]},"example":{"success":true,"data":{"operation":"conversion-rate","result":5},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/business/ctr":{"post":{"tags":["Business Analytics"],"summary":"Click-through rate CTR (percent)","description":"Returns `clicks / impressions × 100` as percent points. Counts are non-negative. `impressions = 0` yields `DIVISION_BY_ZERO` (HTTP 422).","operationId":"businessCtr","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessCtrRequest"},"example":{"clicks":100,"impressions":10000}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessCtrResult"}}}]},"example":{"success":true,"data":{"operation":"ctr","result":1},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/business/cpc":{"post":{"tags":["Business Analytics"],"summary":"Cost per click CPC","description":"Returns `cost / clicks`. `cost` and `clicks` are non-negative. `clicks = 0` yields `DIVISION_BY_ZERO` (HTTP 422).","operationId":"businessCpc","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessCpcRequest"},"example":{"cost":250,"clicks":100}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessCpcResult"}}}]},"example":{"success":true,"data":{"operation":"cpc","result":2.5},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/business/cpm":{"post":{"tags":["Business Analytics"],"summary":"Cost per mille CPM","description":"Returns `cost / impressions × 1000` (cost per 1,000 impressions). `impressions = 0` yields `DIVISION_BY_ZERO` (HTTP 422).","operationId":"businessCpm","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessCpmRequest"},"example":{"cost":500,"impressions":100000}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessCpmResult"}}}]},"example":{"success":true,"data":{"operation":"cpm","result":5},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/business/cpa":{"post":{"tags":["Business Analytics"],"summary":"Cost per acquisition CPA","description":"Returns `cost / conversions`. `conversions = 0` yields `DIVISION_BY_ZERO` (HTTP 422).","operationId":"businessCpa","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessCpaRequest"},"example":{"cost":500,"conversions":25}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessCpaResult"}}}]},"example":{"success":true,"data":{"operation":"cpa","result":20},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/business/cac":{"post":{"tags":["Business Analytics"],"summary":"Customer acquisition cost CAC","description":"Returns `cost / customers`. `customers = 0` yields `DIVISION_BY_ZERO` (HTTP 422).","operationId":"businessCac","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessCacRequest"},"example":{"cost":5000,"customers":50}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessCacResult"}}}]},"example":{"success":true,"data":{"operation":"cac","result":100},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/business/aov":{"post":{"tags":["Business Analytics"],"summary":"Average order value AOV","description":"Returns `revenue / orders`. `revenue` is signed; `orders` is non-negative. `orders = 0` yields `DIVISION_BY_ZERO` (HTTP 422).","operationId":"businessAov","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessAovRequest"},"example":{"revenue":10000,"orders":200}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessAovResult"}}}]},"example":{"success":true,"data":{"operation":"aov","result":50},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/business/retention-rate":{"post":{"tags":["Business Analytics"],"summary":"Retention rate (percent)","description":"Returns `retained / starting × 100` as percent points. Counts are non-negative. `starting = 0` yields `DIVISION_BY_ZERO` (HTTP 422).","operationId":"businessRetentionRate","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessRetentionRateRequest"},"example":{"retained":900,"starting":1000}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessRetentionRateResult"}}}]},"example":{"success":true,"data":{"operation":"retention-rate","result":90},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/business/churn-rate":{"post":{"tags":["Business Analytics"],"summary":"Churn rate (percent)","description":"Returns `churned / starting × 100` as percent points. Counts are non-negative. `starting = 0` yields `DIVISION_BY_ZERO` (HTTP 422).","operationId":"businessChurnRate","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessChurnRateRequest"},"example":{"churned":100,"starting":1000}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessChurnRateResult"}}}]},"example":{"success":true,"data":{"operation":"churn-rate","result":10},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/business/clv":{"post":{"tags":["Business Analytics"],"summary":"Customer lifetime value CLV","description":"Returns `averageOrderValue × purchasesPerPeriod × lifespanPeriods`. No currency is assumed. Exact integer results beyond `Number.MAX_SAFE_INTEGER` are returned as decimal strings and are never rounded.","operationId":"businessClv","parameters":[{"$ref":"#/components/parameters/RequestIdHeader"},{"$ref":"#/components/parameters/ProfileHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessClvRequest"},"example":{"averageOrderValue":50,"purchasesPerPeriod":12,"lifespanPeriods":3}}}},"responses":{"200":{"description":"Successful calculation. The result is in `data.result`.","headers":{"x-zelvyn-status":{"description":"Present only while the API is `degraded`: the request was served, but the platform is experiencing elevated errors or latency. Absent while `operational`.","schema":{"type":"string","enum":["degraded"]}},"deprecation":{"description":"Set to an HTTP-date when this endpoint is deprecated. The endpoint keeps serving until the date in `sunset`, after which it answers 410 ENDPOINT_SUNSET.","schema":{"type":"string"}},"sunset":{"description":"HTTP-date after which the endpoint will stop being served. Requires `deprecation`.","schema":{"type":"string"}},"warning":{"description":"Standard `299` warning carrying a human-readable deprecation notice.","schema":{"type":"string","example":"299 - \"Deprecated endpoint, migrate before the sunset date\""}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessClvResult"}}}]},"example":{"success":true,"data":{"operation":"clv","result":1800},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}},"components":{"schemas":{"RequestId":{"type":"string","minLength":8,"maxLength":64,"pattern":"^[A-Za-z0-9._-]{8,64}$","description":"Correlation id for the request. Echoed from a valid `x-request-id` request header, otherwise a server-generated UUID v4.","example":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f"},"Meta":{"type":"object","additionalProperties":false,"required":["requestId","timestamp"],"description":"Response metadata present on every success and error envelope.","properties":{"requestId":{"$ref":"#/components/schemas/RequestId"},"timestamp":{"type":"string","format":"date-time","description":"Server time (ISO 8601, UTC) at which the response was produced."}}},"ErrorObject":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code from the public taxonomy.","enum":["VALIDATION_ERROR","INVALID_OPERATION","INVALID_DATASET","DIVISION_BY_ZERO","UNDEFINED_RESULT","NOT_FOUND","ENDPOINT_SUNSET","METHOD_NOT_ALLOWED","PAYLOAD_TOO_LARGE","UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","QUOTA_EXCEEDED","INTERNAL_ERROR","SERVICE_UNAVAILABLE"]},"message":{"type":"string","description":"Human-readable explanation. Wording may change; branch on `code`."},"details":{"description":"Optional, code-specific machine-readable context (for example validation `issues`, a division-by-zero `index`, or rate-limit `limit`)."}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["success","error","meta"],"properties":{"success":{"type":"boolean","const":false},"error":{"$ref":"#/components/schemas/ErrorObject"},"meta":{"$ref":"#/components/schemas/Meta"}}},"SuccessResponse":{"type":"object","additionalProperties":false,"required":["success","data","meta"],"properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","description":"Operation-specific result payload (see the endpoint's `data` schema)."},"meta":{"$ref":"#/components/schemas/Meta"}}},"HealthData":{"type":"object","additionalProperties":false,"required":["status","service","apiVersion","version","environment"],"properties":{"status":{"type":"string","const":"ok"},"service":{"type":"string","const":"zelvyn-api"},"apiVersion":{"type":"string","const":"v1"},"version":{"type":"string","description":"Application package version.","example":"0.1.0"},"environment":{"type":"string","description":"Deployment environment (`VERCEL_ENV`, else `NODE_ENV`, else `\"unknown\"`)."}}},"MathAddRequest":{"type":"object","properties":{"values":{"minItems":1,"maxItems":10000,"type":"array","items":{"type":"number"}}},"required":["values"],"additionalProperties":false},"MathSubtractRequest":{"type":"object","properties":{"values":{"minItems":2,"maxItems":10000,"type":"array","items":{"type":"number"}}},"required":["values"],"additionalProperties":false},"MathMultiplyRequest":{"type":"object","properties":{"values":{"minItems":1,"maxItems":10000,"type":"array","items":{"type":"number"}}},"required":["values"],"additionalProperties":false},"MathDivideRequest":{"type":"object","properties":{"values":{"minItems":2,"maxItems":10000,"type":"array","items":{"type":"number"}}},"required":["values"],"additionalProperties":false},"MathPercentOfRequest":{"type":"object","properties":{"percentage":{"type":"number"},"value":{"type":"number"}},"required":["percentage","value"],"additionalProperties":false},"MathPercentageChangeRequest":{"type":"object","properties":{"from":{"type":"number"},"to":{"type":"number"}},"required":["from","to"],"additionalProperties":false},"MathPowerRequest":{"type":"object","properties":{"base":{"type":"number"},"exponent":{"type":"number"}},"required":["base","exponent"],"additionalProperties":false},"MathSqrtRequest":{"type":"object","properties":{"value":{"type":"number"}},"required":["value"],"additionalProperties":false},"MathNthRootRequest":{"type":"object","properties":{"value":{"type":"number"},"degree":{"type":"integer","minimum":1,"maximum":10000}},"required":["value","degree"],"additionalProperties":false},"MathLogRequest":{"type":"object","properties":{"value":{"type":"number"},"base":{"type":"number"}},"required":["value"],"additionalProperties":false},"MathLnRequest":{"type":"object","properties":{"value":{"type":"number"}},"required":["value"],"additionalProperties":false},"MathFactorialRequest":{"type":"object","properties":{"n":{"type":"integer","minimum":0,"maximum":1000}},"required":["n"],"additionalProperties":false},"MathGcdRequest":{"type":"object","properties":{"a":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"b":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["a","b"],"additionalProperties":false},"MathLcmRequest":{"type":"object","properties":{"a":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"b":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["a","b"],"additionalProperties":false},"MathPermutationsRequest":{"type":"object","properties":{"n":{"type":"integer","minimum":0,"maximum":1000},"r":{"type":"integer","minimum":0,"maximum":1000}},"required":["n","r"],"additionalProperties":false},"MathCombinationsRequest":{"type":"object","properties":{"n":{"type":"integer","minimum":0,"maximum":1000},"r":{"type":"integer","minimum":0,"maximum":1000}},"required":["n","r"],"additionalProperties":false},"BusinessProfitRequest":{"type":"object","properties":{"revenue":{"type":"number"},"costs":{"type":"number"}},"required":["revenue","costs"],"additionalProperties":false},"BusinessProfitMarginRequest":{"type":"object","properties":{"revenue":{"type":"number"},"costs":{"type":"number"}},"required":["revenue","costs"],"additionalProperties":false},"BusinessMarkupRequest":{"type":"object","properties":{"price":{"type":"number"},"cost":{"type":"number"}},"required":["price","cost"],"additionalProperties":false},"BusinessRoiRequest":{"type":"object","properties":{"profit":{"type":"number"},"investment":{"type":"number"}},"required":["profit","investment"],"additionalProperties":false},"BusinessRoasRequest":{"type":"object","properties":{"revenue":{"type":"number"},"adSpend":{"type":"number","minimum":0}},"required":["revenue","adSpend"],"additionalProperties":false},"BusinessCagrRequest":{"type":"object","properties":{"beginValue":{"type":"number"},"endValue":{"type":"number"},"periods":{"type":"number","exclusiveMinimum":0}},"required":["beginValue","endValue","periods"],"additionalProperties":false},"BusinessBreakEvenRequest":{"type":"object","properties":{"fixedCosts":{"type":"number"},"price":{"type":"number"},"variableCost":{"type":"number"}},"required":["fixedCosts","price","variableCost"],"additionalProperties":false},"BusinessConversionRateRequest":{"type":"object","properties":{"conversions":{"type":"number","minimum":0},"sessions":{"type":"number","minimum":0}},"required":["conversions","sessions"],"additionalProperties":false},"BusinessCtrRequest":{"type":"object","properties":{"clicks":{"type":"number","minimum":0},"impressions":{"type":"number","minimum":0}},"required":["clicks","impressions"],"additionalProperties":false},"BusinessCpcRequest":{"type":"object","properties":{"cost":{"type":"number","minimum":0},"clicks":{"type":"number","minimum":0}},"required":["cost","clicks"],"additionalProperties":false},"BusinessCpmRequest":{"type":"object","properties":{"cost":{"type":"number","minimum":0},"impressions":{"type":"number","minimum":0}},"required":["cost","impressions"],"additionalProperties":false},"BusinessCpaRequest":{"type":"object","properties":{"cost":{"type":"number","minimum":0},"conversions":{"type":"number","minimum":0}},"required":["cost","conversions"],"additionalProperties":false},"BusinessCacRequest":{"type":"object","properties":{"cost":{"type":"number","minimum":0},"customers":{"type":"number","minimum":0}},"required":["cost","customers"],"additionalProperties":false},"BusinessAovRequest":{"type":"object","properties":{"revenue":{"type":"number"},"orders":{"type":"number","minimum":0}},"required":["revenue","orders"],"additionalProperties":false},"BusinessRetentionRateRequest":{"type":"object","properties":{"retained":{"type":"number","minimum":0},"starting":{"type":"number","minimum":0}},"required":["retained","starting"],"additionalProperties":false},"BusinessChurnRateRequest":{"type":"object","properties":{"churned":{"type":"number","minimum":0},"starting":{"type":"number","minimum":0}},"required":["churned","starting"],"additionalProperties":false},"BusinessClvRequest":{"type":"object","properties":{"averageOrderValue":{"type":"number"},"purchasesPerPeriod":{"type":"number","minimum":0},"lifespanPeriods":{"type":"number","minimum":0}},"required":["averageOrderValue","purchasesPerPeriod","lifespanPeriods"],"additionalProperties":false},"StatisticsMeanRequest":{"type":"object","properties":{"values":{"minItems":1,"maxItems":10000,"type":"array","items":{"type":"number"}}},"required":["values"],"additionalProperties":false},"MathAddResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"add"},"result":{"description":"Add numbers.","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"MathSubtractResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"subtract"},"result":{"description":"Subtract numbers (left to right).","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"MathMultiplyResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"multiply"},"result":{"description":"Multiply numbers.","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"MathDivideResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"divide"},"result":{"description":"Divide numbers (left to right).","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"MathPercentOfResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"percent-of"},"result":{"description":"Percent of a value.","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"MathPercentageChangeResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"percentage-change"},"result":{"description":"Percentage change between two values.","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"MathPowerResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"power"},"result":{"description":"Raise a base to an exponent.","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"MathSqrtResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"sqrt"},"result":{"description":"Square root.","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"MathNthRootResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"nth-root"},"result":{"description":"N-th root.","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"MathLogResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"log"},"result":{"description":"Logarithm to a base (default 10).","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"MathLnResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"ln"},"result":{"description":"Natural logarithm.","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"MathFactorialResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"factorial"},"result":{"description":"Factorial.","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"MathGcdResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"gcd"},"result":{"description":"Greatest common divisor.","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"MathLcmResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"lcm"},"result":{"description":"Least common multiple.","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"MathPermutationsResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"permutations"},"result":{"description":"Permutations P(n, r).","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"MathCombinationsResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"combinations"},"result":{"description":"Combinations C(n, r).","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"BusinessProfitResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"profit"},"result":{"description":"Profit.","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"BusinessProfitMarginResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"profit-margin"},"result":{"description":"Profit margin (percent).","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"BusinessMarkupResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"markup"},"result":{"description":"Markup (percent).","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"BusinessRoiResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"roi"},"result":{"description":"Return on investment ROI (percent).","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"BusinessRoasResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"roas"},"result":{"description":"Return on ad spend ROAS (ratio).","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"BusinessCagrResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"cagr"},"result":{"description":"Compound annual growth rate CAGR (percent).","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"BusinessBreakEvenResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"break-even"},"result":{"description":"Break-even volume (units).","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"BusinessConversionRateResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"conversion-rate"},"result":{"description":"Conversion rate (percent).","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"BusinessCtrResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"ctr"},"result":{"description":"Click-through rate CTR (percent).","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"BusinessCpcResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"cpc"},"result":{"description":"Cost per click CPC.","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"BusinessCpmResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"cpm"},"result":{"description":"Cost per mille CPM.","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"BusinessCpaResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"cpa"},"result":{"description":"Cost per acquisition CPA.","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"BusinessCacResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"cac"},"result":{"description":"Customer acquisition cost CAC.","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"BusinessAovResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"aov"},"result":{"description":"Average order value AOV.","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"BusinessRetentionRateResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"retention-rate"},"result":{"description":"Retention rate (percent).","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"BusinessChurnRateResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"churn-rate"},"result":{"description":"Churn rate (percent).","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"BusinessClvResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"clv"},"result":{"description":"Customer lifetime value CLV.","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."},{"type":"string","pattern":"^-?[0-9]+$","description":"Exact integer result beyond Number.MAX_SAFE_INTEGER, as a decimal string."}]}}},"StatisticsMeanResult":{"type":"object","additionalProperties":false,"required":["operation","result"],"properties":{"operation":{"type":"string","const":"mean"},"result":{"description":"Arithmetic mean of the dataset.","oneOf":[{"type":"number","description":"Finite result within IEEE-754 double precision."}]}}}},"responses":{"BadRequest":{"description":"The request is malformed: wrong types, missing/unknown fields, out-of-range values, or invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"VALIDATION_ERROR","message":"Request validation failed.","details":{"issues":[{"path":"values","code":"too_small","message":"values must contain at least 1 value"}]}},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"Unauthorized":{"description":"A credential was presented but is invalid, revoked, expired, or malformed. Credential existence is never disclosed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Invalid API key."},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"Forbidden":{"description":"The credential is valid but the account is not permitted to use the API (for example, suspended).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"FORBIDDEN","message":"This account is not permitted to use the API."},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"NotFound":{"description":"No endpoint or operation matches the requested path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"INVALID_OPERATION","message":"Unknown operation \"burn-rate\".","details":{"operation":"burn-rate","supported":["profit","profit-margin","markup","roi","roas","cagr","break-even","conversion-rate","ctr","cpc","cpm","cpa","cac","aov","retention-rate","churn-rate","clv"]}},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"MethodNotAllowed":{"description":"The path exists but does not accept this HTTP method. The `allow` response header lists the supported methods.","headers":{"allow":{"description":"Comma-separated list of methods supported by the endpoint.","schema":{"type":"string","example":"POST"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"METHOD_NOT_ALLOWED","message":"This endpoint only accepts POST requests."},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"Gone":{"description":"The endpoint has been retired (`ENDPOINT_SUNSET`). The `sunset` header carries the retirement date; remove the integration and use the replacement named in the response.","headers":{"sunset":{"description":"HTTP-date on which the endpoint stopped being served.","schema":{"type":"string","example":"Wed, 01 Jan 2030 00:00:00 GMT"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"ENDPOINT_SUNSET","message":"This endpoint has been retired.","details":{"sunset":"2030-01-01T00:00:00.000Z"}},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"PayloadTooLarge":{"description":"The request body exceeds the 1048576-byte (1 MiB) limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"PAYLOAD_TOO_LARGE","message":"Request body exceeds the maximum allowed size of 1048576 bytes."},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"UnprocessableEntity":{"description":"The request is well-formed but mathematically or business-undefined for the given input (`DIVISION_BY_ZERO`, `UNDEFINED_RESULT`, or `INVALID_DATASET`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"DIVISION_BY_ZERO","message":"roas requires a non-zero denominator.","details":{"denominator":0}},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"TooManyRequests":{"description":"The caller exceeded its rate limit (`RATE_LIMITED`) or its monthly quota (`QUOTA_EXCEEDED`). The `retry-after` header reports seconds until the rate-limit window resets.","headers":{"retry-after":{"description":"Seconds until the current rate-limit window resets.","schema":{"type":"integer","minimum":1,"example":42}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"RATE_LIMITED","message":"Rate limit exceeded. Slow down and retry shortly.","details":{"limit":60,"windowSeconds":60,"retryAfterSeconds":42}},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"InternalServerError":{"description":"An unexpected internal error occurred. Details are logged server-side and never returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"INTERNAL_ERROR","message":"An unexpected internal error occurred."},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}},"ServiceUnavailable":{"description":"The control plane (authentication, rate limiting, or quota) is temporarily unavailable. Authenticated requests fail closed; anonymous traffic keeps being served.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"SERVICE_UNAVAILABLE","message":"Authentication is temporarily unavailable."},"meta":{"requestId":"3f1c2b7a-9d4e-4f6a-8b2c-1a2b3c4d5e6f","timestamp":"2026-01-15T12:00:00.000Z"}}}}}},"parameters":{"RequestIdHeader":{"name":"x-request-id","in":"header","required":false,"description":"Optional client-supplied correlation id. Must match `^[A-Za-z0-9._-]{8,64}$`. A valid value is echoed in `meta.requestId` and the `x-request-id` response header; an absent or malformed value is replaced by a server-generated UUID v4.","schema":{"$ref":"#/components/schemas/RequestId"}},"ProfileHeader":{"name":"x-zelvyn-profile","in":"header","required":false,"description":"Selects a response field set. One of `compact`, `default`, `detailed`. `default` is the unprofiled v1 contract (`operation` + `result`) and is always available. `compact` and `detailed` are only honoured where the endpoint offers them, and never beyond the profile an administrator has activated. An unsupported value is rejected with 400 VALIDATION_ERROR rather than ignored.","schema":{"type":"string","enum":["compact","default","detailed"],"default":"default","example":"detailed"}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Zelvyn API key","description":"Send the API key as `Authorization: Bearer zlv_<env>_<keyId>_<secret>`. Keys are optional on currently public endpoints."},"apiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Alternative to the `Authorization` header: send the raw API key in `x-api-key`. `Authorization` takes precedence if both are present."}}},"x-zelvyn-limits":{"anonymousRateLimitPerMinute":60,"maxRequestBodyBytes":1048576,"maxDatasetValues":10000,"plans":{"FREE":{"requestsPerMinute":60,"requestsPerMonth":10000,"accountRequestsPerMinute":240,"endpointRequestsPerMinute":60},"PRO":{"requestsPerMinute":600,"requestsPerMonth":1000000,"accountRequestsPerMinute":2400,"endpointRequestsPerMinute":600}},"rateLimitDimensions":[{"dimension":"key","scope":"one API key","limit":"per-key requests per minute"},{"dimension":"account","scope":"plan × environment","limit":"see `plans`"},{"dimension":"endpoint","scope":"one endpoint × one caller","limit":"see `plans`"},{"dimension":"ip","scope":"anonymised caller hash","limit":"anonymousRateLimitPerMinute"},{"dimension":"global","scope":"the whole API","limit":"off unless configured"},{"dimension":"admin","scope":"private admin control plane","limit":"ADMIN_RATE_LIMIT_GLOBAL_PER_MINUTE / ADMIN_RATE_LIMIT_IP_PER_MINUTE / ADMIN_RATE_LIMIT_FAILED_PER_MINUTE (default 120 / 60 / 10 per minute)"}]}}