This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Using REST

Install and configure the REST API, validate connectivity, and use the API reference for client setup and Synthetic Data operations.

1 - 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.