REST API Reference

Configure the Synthetic Data client and interact with it through the REST API.

Base URL (all schema-documented APIs): <GATEWAY_ENDPOINT>/pty/syntheticdata/v2

Authentication

  • AUTH Key: Needed for client authentication
    • Header: Authorization: Bearer <AUTH_KEY>

Common request models

DataInput

Provide exactly one of the following:

  1. inline (base64 CSV string)
  2. uri (cloud URI such as s3://..., gs://..., azure://..., minio://...)
  3. inline_tables (multi-table map: table name -> base64 CSV)
  4. uri_tables (multi-table map: table name -> cloud URI)

Optional:

  • format: csv or parquet (used for inline payloads)

Error model (common behavior)

  • 422 validation error for schema/field violations
  • 403 tier-gated feature not allowed on current tier
  • 429 rate limit exceeded
  • 501 async job tracking not enabled (when server runs without job store)

Async job submission response

Most write endpoints return 202 Accepted immediately:

{
  "job_id": "1a2b3c4d-...",
  "status": "queued",
  "message": "Job submitted for background processing",
  "created_at": "2026-08-04T06:00:00Z"
}

Use the Jobs endpoints to poll completion and fetch context.result.

1. Submit Synthesis Job

POST /synthesize

Submits synthesis operations such as fit, fit_transform, transform, summary, evaluate, validate_relationships, relational_score, get_table_order.

Request body

{
  "model_name": "vine",
  "action": "fit_transform",
  "training_data": {
    "inline": "<BASE64_CSV>"
  },
  "n_samples": 100,
  "parameters": {
    "categorical_cols": ["city"]
  },
  "output": {
    "uri": "s3://my-bucket/synth/output.csv"
  },
  "post_filters": {
    "business_rules": {
      "intervals": { "age": [18, 65] },
      "unique_combinations": [["country", "region"]]
    }
  },
  "pre_filters": {
    "outlier_detection": {
      "contamination": 0.05
    }
  }
}

cURL

curl -X POST "<GATEWAY_ENDPOINT>/pty/syntheticdata/v2/synthesize" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name":"vine",
    "action":"fit_transform",
    "training_data":{"inline":"<BASE64_CSV>"},
    "n_samples":100
  }'

Response

  • 202 Accepted -> JobResponse

2. Submit Privacy Evaluation Job

POST /evaluate/privacy

Evaluates privacy risk (membership inference, sensitive attribute reconstruction, linkage-related checks).

Request body

{
  "train_real_data": { "inline": "<BASE64_CSV>" },
  "test_real_data": { "inline": "<BASE64_CSV>" },
  "synthetic_data": { "inline": "<BASE64_CSV>" },
  "sensitive_columns": ["diagnosis", "income"],
  "k_values": [2, 5, 10],
  "config": {
    "shadow_models": 3,
    "attack_model": "xgboost",
    "random_state": 42
  }
}

cURL

curl -X POST "<GATEWAY_ENDPOINT>/pty/syntheticdata/v2/evaluate/privacy" \
  -H "Content-Type: application/json" \
  -d '{
    "train_real_data":{"inline":"<BASE64_CSV>"},
    "test_real_data":{"inline":"<BASE64_CSV>"},
    "synthetic_data":{"inline":"<BASE64_CSV>"}
  }'

Response

  • 202 Accepted -> JobResponse
  • Final job result (context.result) follows PrivacyEvaluationResponse

3. Submit Causal Fidelity Evaluation Job

POST /evaluate/causal

Runs one or more causal fidelity analyses: treatment effect, decision consistency, fairness shift.

Request body

{
  "real_data": { "inline": "<BASE64_CSV>" },
  "synthetic_data": { "inline": "<BASE64_CSV>" },
  "treatment_col": "treatment",
  "outcome_col": "outcome",
  "covariates": ["age", "income"],
  "target_col": "label",
  "feature_cols": ["age", "income", "score"],
  "task_type": "classification",
  "sensitive_attr": "gender",
  "config": {
    "ate_threshold": 0.15,
    "random_state": 123
  }
}

cURL

curl -X POST "<GATEWAY_ENDPOINT>/pty/syntheticdata/v2/evaluate/causal" \
  -H "Content-Type: application/json" \
  -d '{
    "real_data":{"inline":"<BASE64_CSV>"},
    "synthetic_data":{"inline":"<BASE64_CSV>"},
    "treatment_col":"treatment",
    "outcome_col":"outcome"
  }'

Response

  • 202 Accepted -> JobResponse
  • Final job result (context.result) follows CausalEvaluationResponse

4. Submit Certification Job

POST /certify

Computes overall certification score and component breakdown (fidelity, privacy, utility, completeness).

Request body

{
  "real_data": { "inline": "<BASE64_CSV>" },
  "synthetic_data": { "inline": "<BASE64_CSV>" },
  "categorical_cols": ["region", "product"],
  "target_col": "purchased",
  "task_type": "classification",
  "include_privacy_attacks": true,
  "train_real_data": { "inline": "<BASE64_CSV>" },
  "test_real_data": { "inline": "<BASE64_CSV>" },
  "feature_cols": ["age", "income"],
  "sensitive_col": "diagnosis",
  "quasi_identifiers": ["zipcode", "age", "gender"],
  "fidelity_weight": 0.4,
  "privacy_weight": 0.3,
  "utility_weight": 0.2,
  "completeness_weight": 0.1
}

cURL

curl -X POST "<GATEWAY_ENDPOINT>/pty/syntheticdata/v2/certify" \
  -H "Content-Type: application/json" \
  -d '{
    "real_data":{"inline":"<BASE64_CSV>"},
    "synthetic_data":{"inline":"<BASE64_CSV>"}
  }'

Response

  • 202 Accepted -> JobResponse
  • Final job result (context.result) follows CertificationResponse

5. Submit Conditional Generation Job

POST /generate/conditional

Generates synthetic data conditioned on filters and optional drift injection.

Request body

{
  "real_data": { "inline": "<BASE64_CSV>" },
  "model_name": "vine",
  "categorical_cols": ["status", "fraud"],
  "n_samples": 50,
  "conditions": {
    "fraud": 1,
    "age": ">50",
    "status": "active"
  },
  "amplify_patterns": {
    "fraud": 2.0
  },
  "inject_drift": {
    "income": -10000,
    "age": -5
  },
  "random_state": 42
}

cURL

curl -X POST "<GATEWAY_ENDPOINT>/pty/syntheticdata/v2/generate/conditional" \
  -H "Content-Type: application/json" \
  -d '{
    "real_data":{"inline":"<BASE64_CSV>"},
    "model_name":"vine",
    "n_samples":50,
    "conditions":{"fraud":1}
  }'

Response

  • 202 Accepted -> JobResponse
  • Final job result (context.result) follows ConditionalResult

6. List Production Models

GET /models

Returns model versions currently in production stage.

Query parameters

  • model_type (optional): filter by algorithm class (for example vine)
  • all_metrics (optional, default false): include all logged metrics

cURL

curl "<GATEWAY_ENDPOINT>/pty/syntheticdata/v2/models?model_type=vine&all_metrics=true"

Response

  • 200 OK
  • Body: ProductionModelInfo[]

Example:

[
  {
    "model_name": "vine_v1",
    "model_type": "vine",
    "model_version": "v1",
    "semantic_version": "2.0",
    "stage": "Production",
    "input_schema": {"age": "float", "salary": "float", "region": "string"},
    "metrics": {"tabsyndex_overall": 0.627},
    "registered_at": "2026-03-18T11:18:03+00:00"
  }
]

7. Submit Horizontal Benchmark Job

POST /benchmark/horizontal

Benchmarks multiple models on one dataset.

Request body

Provide either dataset_name or custom data (+ categorical_columns, target_variable).

{
  "data": { "inline": "<BASE64_CSV>" },
  "categorical_columns": ["region"],
  "target_variable": "purchased",
  "models": ["smote", "tabdiff"],
  "n_rows_override": 1000
}

cURL

curl -X POST "<GATEWAY_ENDPOINT>/pty/syntheticdata/v2/benchmark/horizontal" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_name":"heart",
    "models":["smote","tabdiff"]
  }'

Response

  • 202 Accepted -> JobResponse
  • Final job result (context.result) follows HorizontalBenchmarkResponse

8. Submit Vertical Benchmark Job

POST /benchmark/vertical

Benchmarks one model across all predefined hyperparameter presets.

Request body

Provide either dataset_name or custom data (+ categorical_columns, target_variable).

{
  "data": { "inline": "<BASE64_CSV>" },
  "categorical_columns": ["region"],
  "target_variable": "purchased",
  "model": "smote",
  "n_rows_override": 1000
}

cURL

curl -X POST "<GATEWAY_ENDPOINT>/pty/syntheticdata/v2/benchmark/vertical" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_name":"heart",
    "model":"smote"
  }'

Response

  • 202 Accepted -> JobResponse
  • Final job result (context.result) follows VerticalBenchmarkResponse

9. Job APIs (available when job store is enabled)

These routes are mounted at /jobs via pty_ai_job_state_lib and are part of the public API surface when async job tracking is configured.

9.1 List jobs

GET /jobs

Optional query parameters observed in tests:

  • status (for example completed)
curl "<GATEWAY_ENDPOINT>/pty/syntheticdata/v2/jobs?status=completed"

9.2 Get job details

GET /jobs/{job_id}

curl "<GATEWAY_ENDPOINT>/pty/syntheticdata/v2/jobs/<JOB_ID>"

Typical fields include job_id, status, message, progress, and context.

9.3 Get job history

GET /jobs/{job_id}/history

curl "<GATEWAY_ENDPOINT>/pty/syntheticdata/v2/jobs/<JOB_ID>/history"

9.4 Delete job

DELETE /jobs/{job_id}

curl -X DELETE "<GATEWAY_ENDPOINT>/pty/syntheticdata/v2/jobs/<JOB_ID>"

Expected: 204 No Content when deletion succeeds.


Last modified : August 04, 2026