API Docs — DataMerase

API Documentation

A human-readable reference for integrating with the DataMerase API directly. For the machine-readable version, GET /docs with a valid API key.

Getting started

Base URL	`https://datamerase.io`
Auth header	`X-API-Key: <your key>`
Content type	`application/json` for JSON bodies, `multipart/form-data` for file upload

Every endpoint requires the X-API-Key header except GET /, GET /api-docs, GET /mcp, GET /mcp/download, and static assets. Requests to a protected endpoint with a missing or incorrect key get back 401 unauthorized.

Don't have a key yet? Contact us at admin@datamerase.io for API access.

Response envelope

Every JSON endpoint (all of them except GET /download/<job_id>, which streams a CSV file) returns the same shape:

{
  "success": <bool>,
  "data": <endpoint-specific payload, or null on error>,
  "error": <{"message": "...", "code": "..."}, or null on success>
}

Endpoints

GET /health key required

Server status, GPU availability, and current job counts. Good for checking capacity before starting a job.

curl

curl https://datamerase.io/health \
  -H "X-API-Key: YOUR_API_KEY"

response

{
  "success": true,
  "data": {
    "status": "ok",
    "gpu_available": false,
    "gpu_name": null,
    "active_jobs": 0,
    "total_jobs": 3,
    "timestamp": "2026-08-03T17:00:00+00:00"
  },
  "error": null
}

POST /upload key required

Upload a CSV/Excel file (.csv, .xlsx, .xls, max 50MB). Returns a job_id plus auto-detected column types and data-quality warnings.

request body — multipart/form-data

file	the CSV/Excel file

curl

curl -X POST https://datamerase.io/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@housing.csv"

response

{
  "success": true,
  "data": {
    "job_id": "3898a584-9674-4ec5-a812-b93d9e3f1205",
    "columns": ["SalePrice", "Gr Liv Area", "Neighborhood", "Lot Config"],
    "col_types": {
      "SalePrice": "continuous",
      "Gr Liv Area": "continuous",
      "Neighborhood": "categorical",
      "Lot Config": "categorical"
    },
    "n_rows": 1460,
    "warnings": ["Column 'Lot Config' has 4 missing values"]
  },
  "error": null
}

POST /detect_family key required

Detect the statistical distribution family of a target column — useful if you want to see what family: "auto" would pick before starting generation.

request body — application/json

job_id	required — from `/upload`
target_col	required — column name

curl

curl -X POST https://datamerase.io/detect_family \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "3898a584-...", "target_col": "SalePrice"}'

response

{ "success": true, "data": { "family": "gaussian" }, "error": null }

POST /generate key required

Start an asynchronous generation job for an uploaded dataset. Returns immediately with status: "started" — poll GET /status/<job_id> for progress.

request body — application/json

job_id	required
target_col	optional — numeric column to model (Bambi). Omit for text-only generation.
continuous_cols	optional array, default `[]` — other numeric columns (Vine copula)
categorical_cols	optional array, default `[]`
text_cols	optional array, default `[]` — free-text columns (GPT-2)
n_samples	optional int, default `3000`
draws / tune	optional int, default `1000` / `1000` — PyMC sampler settings
family	optional, default `"auto"`
text_epochs	optional int, default `3`

curl

curl -X POST https://datamerase.io/generate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "3898a584-...",
    "target_col": "SalePrice",
    "continuous_cols": ["Gr Liv Area"],
    "categorical_cols": ["Neighborhood"],
    "n_samples": 1000
  }'

response

{
  "success": true,
  "data": { "status": "started", "job_id": "3898a584-..." },
  "error": null
}

GET /status/<job_id> key required

Poll the status of a generation job.

curl

curl https://datamerase.io/status/3898a584-... \
  -H "X-API-Key: YOUR_API_KEY"

response (done)

{
  "success": true,
  "data": {
    "job_id": "3898a584-...",
    "status": "done",
    "progress": ["STEP 1: Bambi → Synthetic Y", "...", "PIPELINE FINISHED"],
    "metrics": {
      "numeric": {
        "KS (Avg)": 0.19, "WD (Avg)": 7296.68,
        "Corr Diff (F-Norm)": 1.45, "DCR (Avg)": 1.23,
        "Duplicate Rate (%)": 0.0, "TSTR R²": 0.25,
        "TSTR RMSE": 41283.48, "family": "gaussian"
      },
      "rows_generated": 1000,
      "columns": ["Gr Liv Area", "Neighborhood", "SalePrice"]
    },
    "error": null
  },
  "error": null
}

GET /download/<job_id> key required

Download the generated synthetic_data.csv for a completed job. Unlike every other endpoint, a successful response is the raw CSV file (Content-Type: text/csv), not a JSON envelope — request errors (e.g. job not found or not finished yet) still come back as the usual JSON error envelope.

curl

curl https://datamerase.io/download/3898a584-... \
  -H "X-API-Key: YOUR_API_KEY" \
  -o synthetic_data.csv

Column roles — target / continuous / categorical / text / ignore

Every column in your uploaded file should map to exactly one role. The first four are explicit request fields on /generate; ignore isn't a field at all — a column is excluded from the synthetic output simply by leaving it out of target_col and every one of the three arrays below.

target_colsingle numeric outcome column, modeled with Bambi

continuous_colsother numeric columns, modeled via vine copula

categorical_colscategorical columns

text_colsfree-text columns, modeled with GPT-2

ignoreomit from every list above — not sent to the API at all

Rate limits & concurrency

Limit	Behavior
3 concurrent jobs	the server runs at most 3 `/generate` jobs at once. A 4th concurrent request gets `429 capacity_exceeded` — retry shortly.
One job per `job_id`	calling `/generate` again on a `job_id` that's already running or finished returns `409 job_conflict`. Upload the file again to get a fresh `job_id` if you need to re-run.

Error codes you may see

HTTP	code	meaning
401	`unauthorized`	missing or incorrect `X-API-Key`
400	`missing_file` / `unsupported_file_type` / `empty_file` / `no_data_rows` / `encoding_error` / `parse_error`	problem with the uploaded file
400	`column_not_found`	a referenced column name doesn't exist in the uploaded file (message lists the available columns)
400	`invalid_job` / `missing_target`	bad or missing `job_id`, or neither `target_col` nor `text_cols` given
409	`job_conflict`	`job_id` already running or done
429	`capacity_exceeded`	3 jobs already running
404	`not_found` / `no_result`	unknown route, or job not finished yet