API Documentation

Overview

The AddMaple Synthetic Data API provides programmatic access to our synthetic data generation capabilities. Generate realistic test data, create complex datasets, and integrate synthetic data generation directly into your development workflows.

Authentication

All API requests require authentication using an API key. Include your API key in the request headers:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.synthetic.addmaple.com/v1/generate

Base URL

https://api.synthetic.addmaple.com/v1

Endpoints

Generate Synthetic Data

POST /generate

Generate synthetic data based on a schema definition.

Request Body

{
  "globalPrompt": "E-commerce customer data",
  "numRows": 1000,
  "columns": [
    {
      "name": "customer_name",
      "type": "LLMText",
      "settings": {
        "prompt": "Generate realistic customer names"
      }
    },
    {
      "name": "age",
      "type": "Number",
      "settings": {
        "min": 18,
        "max": 75
      }
    }
  ]
}

Response

{
  "success": true,
  "jobId": "job_123456",
  "status": "pending",
  "estimatedTime": "2-5 minutes"
}

Check Job Status

GET /jobs/{jobId}/status

Check the status of a data generation job.

Response

{
  "success": true,
  "status": "completed",
  "progress": 100,
  "rowsGenerated": 1000,
  "downloadUrl": "https://api.synthetic.addmaple.com/v1/jobs/job_123456/download"
}

Download Generated Data

GET /jobs/{jobId}/download

Download the generated synthetic data as CSV.

Data Types

LLMText

AI-generated text content using language models.

Settings:

• prompt: Custom prompt for text generation
• mode: "simple" or "structured"

Number

Numeric values within specified ranges.

Settings:

• min: Minimum value (inclusive)
• max: Maximum value (inclusive)

Categorical

Values from a predefined list of options.

Settings:

• categories: Array of possible values

Boolean

True/false values.

Settings:

• truePercentage: Percentage of true values (default: 50)

Date

Date values within specified ranges.

Settings:

• start: Start date (ISO format)
• end: End date (ISO format)

Rate Limits

• Free Tier: 100 requests per hour, 10,000 rows per day
• Pro Tier: 1,000 requests per hour, 100,000 rows per day
• Enterprise: Custom limits

Error Codes

Code	Description
400	Bad Request - Invalid schema or parameters
401	Unauthorized - Invalid or missing API key
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server-side error

SDKs and Libraries

JavaScript/Node.js

npm install @addmaple/synthetic-data

import { SyntheticDataClient } from '@addmaple/synthetic-data';

const client = new SyntheticDataClient('YOUR_API_KEY');

const job = await client.generate({
  globalPrompt: "E-commerce customer data",
  numRows: 1000,
  columns: [
    { name: "name", type: "LLMText" },
    { name: "age", type: "Number", settings: { min: 18, max: 75 } }
  ]
});

const data = await client.waitForCompletion(job.jobId);

Python

pip install addmaple-synthetic-data

from addmaple_synthetic import SyntheticDataClient

client = SyntheticDataClient(api_key="YOUR_API_KEY")

job = client.generate(
    global_prompt="E-commerce customer data",
    num_rows=1000,
    columns=[
        {"name": "name", "type": "LLMText"},
        {"name": "age", "type": "Number", "settings": {"min": 18, "max": 75}}
    ]
)

data = client.wait_for_completion(job["jobId"])

Webhooks

Configure webhooks to receive notifications when jobs complete:

POST /webhooks

{
  "url": "https://your-app.com/webhook",
  "events": ["job.completed", "job.failed"]
}

Best Practices

1. Use specific prompts for better data quality
2. Start small when testing new schemas
3. Cache results when possible to avoid regeneration
4. Monitor rate limits and implement proper retry logic
5. Validate data after generation to ensure quality

Support

Need help with the API? Contact our developer support:

• Email: api-support@addmaple.com
• Documentation: docs.synthetic.addmaple.com
• Status Page: status.synthetic.addmaple.com