API Reference

The ABS REST API provides three endpoints for sample-size calculations and validation, plus a health check. All responses use JSON, and the base URL is https://abs.codecide.net/api.

No authentication is required.

Response format

Every endpoint returns a JSON object with a success field.

Success (200)

{
  "success": true,
  "result": { ... },
  "metadata": {
    "processingTimeMs": 1.234,
    "inputCount": 20,
    "outputCount": 4
  }
}

• result – endpoint-specific data (see below).
• metadata.processingTimeMs – server-side processing time in milliseconds.
• metadata.inputCount – number of distinct input fields received.
• metadata.outputCount – number of top-level keys in the result object.

Error

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": [],
    "validationErrors": []
  }
}

• error.code – one of INVALID_PAYLOAD, VALIDATION_ERROR, CALCULATION_ERROR, INTERNAL_ERROR, NOT_FOUND.
• error.message – always present.
• error.details – list of Zod issues (only for INVALID_PAYLOAD).
• error.validationErrors – list of domain validation errors (only for VALIDATION_ERROR).

Endpoints

GET /health

Returns server status and uptime.

Response 200

{
  "status": "ok",
  "timestamp": "2025-04-01T12:00:00Z",
  "uptime": 3600
}

---

POST /api/calculate

Full sample-size calculation for an A/B test. Computes required sample size, test duration, feasibility, and sensitivity/power curves.

Request body (JSON)

All fields except standardDeviation, mdeAbsolute (when mdeMode is relative), arpu, priorAlpha, and priorBeta are required.

Parameter	Type	Required	Description
metricType	string	yes	"proportion", "continuous", or "count"
testMethod	string	yes	"z-test", "t-test", "chi-squared", or "bayes-beta-binomial"
framework	string	yes	"frequentist" or "bayesian"
tailType	string	yes	"one-tailed" or "two-tailed"
baselineRate	number	yes	Control conversion rate, decimal between 0 and 1 (exclusive)
standardDeviation	number		Required for continuous metrics
mdeMode	string	yes	"absolute" or "relative"
mdeAbsolute	number		Required when mdeMode = "absolute". Absolute MDE in same units as baseline
mdeRelative	number	yes	Relative MDE as percentage of baseline (e.g. 10 = 10%). Used when mdeMode = "relative"
alpha	number	yes	Significance level, 0–1
power	number	yes	Desired power, 0.5–1
numberOfVariants	integer	yes	≥ 2 (including control)
allocationRatios	number[]	yes	Traffic split per variant, must sum to 1
correctionMethod	string	yes	"none", "bonferroni", "bh" (Benjamini-Hochberg), or "dunnett"
dailyTraffic	integer	yes	Number of users available per day, ≥ 0
dropoutRate	number	yes	Expected dropout percentage, 0–100
minimumRuntimeDays	integer	yes	Minimum days to run test (informational)
arpu	number		Average revenue per user for projection
continuityCorrection	boolean	yes	Apply continuity correction (proportions only)
priorAlpha	number		Beta prior alpha (Bayesian). Defaults to 1
priorBeta	number		Beta prior beta (Bayesian). Defaults to 1

Example request

{
  "metricType": "proportion",
  "testMethod": "z-test",
  "framework": "frequentist",
  "tailType": "two-tailed",
  "baselineRate": 0.05,
  "mdeMode": "relative",
  "mdeRelative": 10,
  "alpha": 0.05,
  "power": 0.80,
  "numberOfVariants": 2,
  "allocationRatios": [0.5, 0.5],
  "correctionMethod": "none",
  "dailyTraffic": 10000,
  "dropoutRate": 0,
  "minimumRuntimeDays": 14,
  "continuityCorrection": false
}

Success response (200)

The result object contains:

• outputs – calculation results (sampleSizePerVariant, totalSampleSize, etc.)
• validationErrors – list of warnings (non-blocking)
• sensitivityData – array of points for sensitivity curves
• powerCurveData – array of points for power curves

{
  "success": true,
  "result": {
    "outputs": {
      "sampleSizePerVariant": 25230,
      "totalSampleSize": 50460,
      "adjustedTotalSampleSize": 50460,
      "testDurationDays": 6,
      "testDurationWeeks": 0.86,
      "feasibility": "feasible",
      "effectiveMDEAbsolute": 0.005,
      "effectiveMDERelative": 10,
      "allocationEfficiencyCost": 0,
      "projectedIncrementalRevenue": null
    },
    "validationErrors": [],
    "sensitivityData": [
      {
        "mdeMultiplier": 0.5,
        "mdeAbsolute": 0.0025,
        "mdeRelative": 5,
        "sampleSizePerVariant": 100000,
        "totalSampleSize": 200000
      }
    ],
    "powerCurveData": [
      {
        "sampleSize": 25230,
        "power": 0.8
      }
    ]
  },
  "metadata": { ... }
}

Error responses

• 400 – INVALID_PAYLOAD – Request body failed schema validation (details contains Zod issues).
• 400 – VALIDATION_ERROR – Blocking domain validation errors (validationErrors contains details).
• 400 – CALCULATION_ERROR – Unexpected runtime failure inside a calculation.
• 500 – INTERNAL_ERROR – Unhandled server error.

curl example

curl -X POST https://abs.codecide.net/api/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "metricType": "proportion",
    "testMethod": "z-test",
    "framework": "frequentist",
    "tailType": "two-tailed",
    "baselineRate": 0.05,
    "mdeMode": "relative",
    "mdeRelative": 10,
    "alpha": 0.05,
    "power": 0.80,
    "numberOfVariants": 2,
    "allocationRatios": [0.5, 0.5],
    "correctionMethod": "none",
    "dailyTraffic": 10000,
    "dropoutRate": 0,
    "minimumRuntimeDays": 14,
    "continuityCorrection": false
  }'

---

POST /api/validate

Validates calculator inputs without running the full calculation. Returns validation errors, a boolean flag for blocking errors, and a warning flag.

Request body

Identical to POST /api/calculate. All fields required.

Success response (200)

{
  "success": true,
  "result": {
    "validationErrors": [
      {
        "field": "baselineRate",
        "message": "Baseline rate must be between 0 and 1 (exclusive).",
        "severity": "error"
      }
    ],
    "hasErrors": true,
    "hasWarnings": false
  },
  "metadata": { ... }
}

curl example

curl -X POST https://abs.codecide.net/api/validate \
  -H "Content-Type: application/json" \
  -d '{
    "metricType": "proportion",
    "testMethod": "z-test",
    "framework": "frequentist",
    "tailType": "two-tailed",
    "baselineRate": 0.05,
    "mdeMode": "relative",
    "mdeRelative": 10,
    "alpha": 0.05,
    "power": 0.80,
    "numberOfVariants": 2,
    "allocationRatios": [0.5, 0.5],
    "correctionMethod": "none",
    "dailyTraffic": 10000,
    "dropoutRate": 0,
    "minimumRuntimeDays": 14,
    "continuityCorrection": false
  }'

---

POST /api/inverse-mde

Solves for the minimum detectable effect (absolute) given a fixed sample size per variant.

Request body

Parameter	Type	Required	Description
baselineRate	number	yes	Control rate, 0–1 (exclusive)
fixedN	integer	yes	Available sample size per variant, ≥ 2
alpha	number	yes	Significance level
power	number	yes	Desired power
tailType	string	yes	"one-tailed" or "two-tailed"
metricType	string	yes	"proportion", "continuous", or "count"
standardDeviation	number		Required for continuous metrics

Success response (200)

{
  "success": true,
  "result": {
    "mdeAbsolute": 0.0098
  },
  "metadata": { ... }
}

Error responses

• 400 – INVALID_PAYLOAD – schema failure.
• 400 – CALCULATION_ERROR – convergence failure or nonsensical parameters (e.g., fixedN too small).

curl example

curl -X POST https://abs.codecide.net/api/inverse-mde \
  -H "Content-Type: application/json" \
  -d '{
    "baselineRate": 0.05,
    "fixedN": 10000,
    "alpha": 0.05,
    "power": 0.80,
    "tailType": "two-tailed",
    "metricType": "proportion"
  }'

---

GET /api/openapi.json

Returns the full OpenAPI 3.0.3 specification for the API. Useful for generating client code or exploring with tools like Swagger or Scalar.

Response 200

A JSON object conforming to the OpenAPI 3.0.3 standard.

curl https://abs.codecide.net/api/openapi.json

---

GET /api/docs

Interactive API documentation page rendered by Scalar. Returns HTML; point a browser here to explore the API visually.

Additional resources

• OpenAPI spec served at /api/openapi.json.
• Interactive docs at https://abs.codecide.net/api/docs.
• MCP (Model Context Protocol) endpoint available at https://abs.codecide.net/mcp for AI assistant integration.