REST API Reference

The Twynvex REST API lets you trigger synthetic data generation, poll job status, download results, and manage schema definitions from any language or CI/CD pipeline.

Base URL

https://api.twynvex.com/v1

All endpoints are versioned under /v1. Responses use application/json. Error responses include error.code and error.message fields.

Authentication

All API requests require a Bearer token. Pass your API key in the Authorization header:

Authorization: Bearer twx_sk_live_yourKeyHere

API keys are available in your dashboard under Settings → API Keys. Prototype tier keys are rate-limited. Build and Scale tier keys have no rate limit on the generation API.

POST /generate

Create a new generation job. Returns a job object immediately. Poll GET /jobs/{id} to check completion.

Creates a generation job from a schema ID and generation parameters. The job runs asynchronously — poll /jobs/{id} for status.

Request body

Parameter	Type	Required	Description
`schema_id`	string	yes	ID of a previously uploaded schema object.
`num_rows`	integer	yes	Number of synthetic rows to generate. Max: 50M on Scale tier.
`tail_weight`	float	no	0.0–1.0. Fraction of rows drawn from distribution tail regions. Default: 0.0 (standard distribution). Higher values increase rare-event coverage.
`label_ratio`	object	no	Target class ratios for labeled columns. E.g., `{"fraud": 0.15}`.
`output_format`	string	no	`csv`, `parquet`, or `jsonl`. Default: `parquet`.
`seed`	integer	no	Random seed for reproducible generation. Default: random.

Curl example

curl -X POST https://api.twynvex.com/v1/generate \
  -H "Authorization: Bearer twx_sk_live_yourKey" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "sch_4a7e9f...",
    "num_rows": 500000,
    "tail_weight": 0.4,
    "label_ratio": {"fraud": 0.15},
    "output_format": "parquet"
  }'

Response

{
  "id": "gen_7f3a2b...",
  "status": "running",
  "schema_id": "sch_4a7e9f...",
  "num_rows": 500000,
  "created_at": "2026-05-14T09:41:22Z",
  "estimated_seconds": 28
}

GET /jobs/{id}

Poll the status of a generation job. Statuses: running, complete, failed.

Returns the current state of a generation job. When status is complete, the report object is populated and output_url is available.

Curl example

curl https://api.twynvex.com/v1/jobs/gen_7f3a2b \
  -H "Authorization: Bearer twx_sk_live_yourKey"

Response (complete)

{
  "id": "gen_7f3a2b...",
  "status": "complete",
  "num_rows": 500000,
  "output_url": "https://outputs.twynvex.com/gen_7f3a2b/synthetic.parquet?token=...",
  "output_expires_at": "2026-05-15T09:41:55Z",
  "report": {
    "fidelity_score": 0.93,
    "utility_auc": 0.91,
    "privacy_nn_dist": 0.84,
    "column_js_divergence": {
      "amount": 0.031,
      "category": 0.018,
      "hour": 0.012,
      "fraud": 0.002
    }
  },
  "completed_at": "2026-05-14T09:41:55Z"
}

GET /jobs/{id}/download

Redirects to a pre-signed download URL for the completed job output. URL is valid for 24 hours. Equivalent to output_url in the job object.

Returns a 302 Redirect to the output file URL. You can use this endpoint directly in download scripts.

Curl example

curl -L -o synthetic_train.parquet \
  https://api.twynvex.com/v1/jobs/gen_7f3a2b/download \
  -H "Authorization: Bearer twx_sk_live_yourKey"

POST /schemas

Upload a schema definition. Either provide a sample file (multipart) or a JSON schema body.

Creates a schema object. Pass either a multipart/form-data request with a sample CSV file, or a application/json body with explicit column definitions. Raw sample rows are discarded after fitting.

JSON schema body

curl -X POST https://api.twynvex.com/v1/schemas \
  -H "Authorization: Bearer twx_sk_live_yourKey" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "fraud-transactions-v2",
    "columns": [
      {"name": "amount",   "type": "float",       "min": 0.01, "max": 50000, "dist": "log-normal"},
      {"name": "category", "type": "categorical", "values": ["retail","food","travel","other"]},
      {"name": "hour",     "type": "int",         "min": 0, "max": 23},
      {"name": "fraud",    "type": "categorical", "values": ["legit","fraud"]}
    ]
  }'

Response

{
  "id": "sch_4a7e9f...",
  "name": "fraud-transactions-v2",
  "column_count": 4,
  "created_at": "2026-05-14T09:40:01Z"
}

GET /schemas/{id}

Retrieve a schema definition by ID.

Returns the schema definition including column definitions, fitted distribution parameters (if a sample was provided), and creation timestamp.

Curl example

curl https://api.twynvex.com/v1/schemas/sch_4a7e9f \
  -H "Authorization: Bearer twx_sk_live_yourKey"

Python SDK

The Python SDK wraps the REST API with a more ergonomic interface. All REST endpoints have SDK equivalents:

REST endpoint	SDK equivalent
`POST /schemas` (from CSV)	`twx.from_csv("data.csv")`
`POST /schemas` (manual)	`schema = twx.Schema(); schema.add_column(...)`
`GET /schemas/{id}`	`twx.get_schema("sch_...")`
`POST /generate`	`schema.generate(num_rows=..., tail_weight=...)`
`GET /jobs/{id}`	`job.refresh(); job.status`
`GET /jobs/{id}/download`	`job.to_dataframe()`, `job.to_parquet()`, `job.to_csv()`

The SDK automatically polls job status with exponential backoff when you call to_dataframe() or to_parquet() — you don't need to implement polling logic yourself.