Documentation

DDL to Data API Guide

Everything you need to generate realistic test data from your SQL schemas

Getting Started

DDL to Data lets you generate realistic test data from SQL CREATE TABLE statements in three simple steps:

Get API Key

Create Schema

POST your CREATE TABLE DDL

Generate Data

GET realistic JSON data

Get Free API Key

Authentication

All API requests require authentication via the X-API-Key header.

curl -H "X-API-Key: your_api_key_here" \
  https://ddltodata.com/schemas

Keep Your Key Secret

Your API key grants access to your account. Never expose it in client-side code or public repositories.

API Endpoints

GET/schemas

Retrieve a list of all your registered schema names.

Response

{
  "tables": ["users", "orders", "products"]
}

Example

curl -H "X-API-Key: YOUR_KEY" \
  https://ddltodata.com/schemas

POST/schemas

Parameters

namestringrequired- Unique table name

ddlstringrequired- SQL CREATE TABLE statement

Request Body

{
  "name": "users",
  "ddl": "CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    first_name VARCHAR(50),
    last_name VARCHAR(50),
    email VARCHAR(100) UNIQUE,
    created_at TIMESTAMP
  );"
}

Response

{
  "message": "Schema 'users' created successfully"
}

Example

curl -X POST https://ddltodata.com/schemas \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"users","ddl":"CREATE TABLE users (id INT, name VARCHAR(50), email VARCHAR(100));"}'

GET/generate/{table_name}

Generate synthetic JSON data for the specified table. The data will have realistic values based on column names.

Parameters

table_namestringrequired- Name of the schema to generate data for

rowsinteger- Number of rows to generate (default: 10, max: 10000)

Response

[
  {
    "id": 1,
    "first_name": "Sarah",
    "last_name": "Johnson",
    "email": "sarah.johnson@gmail.com",
    "created_at": "2024-03-15T09:23:41"
  },
  {
    "id": 2,
    "first_name": "Michael",
    "last_name": "Chen",
    "email": "m.chen@outlook.com",
    "created_at": "2024-03-14T14:56:12"
  }
]

Example

curl -H "X-API-Key: YOUR_KEY" \
  "https://ddltodata.com/generate/users?rows=100"

DELETE/schemas/{table_name}

Delete an existing schema and remove it from your account.

Parameters

table_namestringrequired- Name of the schema to delete

Response

{
  "message": "Schema 'users' deleted successfully"
}

Example

curl -X DELETE https://ddltodata.com/schemas/users \
  -H "X-API-Key: YOUR_KEY"

GET/me

Get information about your account, including plan details and usage statistics.

Response

{
  "email": "you@example.com",
  "plan": "free",
  "calls_month": 45,
  "rows_month": 2500,
  "quota_calls_month": 100,
  "quota_rows_month": 5000
}

Example

curl -H "X-API-Key: YOUR_KEY" \
  https://ddltodata.com/me

Smart Data Types

DDL to Data automatically detects column types based on names and generates appropriate realistic values:

Column Pattern	Generated Data	Example
id, *_id	Sequential integers	1, 2, 3...
email	Valid email addresses	john.doe@gmail.com
first_name, name	Person names	Sarah, Michael
last_name, surname	Family names	Johnson, Chen
phone, mobile	Phone numbers	+1-555-123-4567
address, street	Street addresses	123 Main St
city	City names	New York, London
country	Country names	United States
zip, postal	Postal codes	10001, SW1A 1AA
price, amount, cost	Decimal numbers	149.99
url, website	URLs	https://example.com
*_at, date, timestamp	ISO timestamps	2024-03-15T09:23:41
description, bio, text	Lorem ipsum text	Lorem ipsum dolor...
is_, has_	Boolean values	true, false
uuid	UUID v4	550e8400-e29b-41d4-...

Foreign Keys & Relationships

DDL to Data supports foreign key relationships, allowing you to generate consistent data across related tables.

Use the POST /relationships endpoint to define how tables relate:

curl -X POST https://ddltodata.com/relationships \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_table": "users",
    "parent_column": "id",
    "child_table": "orders",
    "child_column": "user_id"
  }'

Rate Limits & Plans

Plan	API Calls/Month	Rows/Month	Price
Free	100	5,000	$0
Starter	500	50,000	$19/mo
Pro	Unlimited	250,000	$79/mo
Enterprise	Custom	Custom	Contact us

View full pricing details →

Error Handling

The API returns standard HTTP status codes with JSON error details:

400

Bad Request - Invalid DDL syntax or missing required fields

401

Unauthorized - Missing or invalid API key

403

Forbidden - Rate limit exceeded or email not verified

404

Not Found - Schema or endpoint not found

429

Too Many Requests - Rate limit exceeded

500

Server Error - Internal server error

Error Response Format

{
  "detail": "Schema 'users' not found"
}

Code Examples

import requests

API_KEY = "your_api_key"
BASE_URL = "https://ddltodata.com"
headers = {"X-API-Key": API_KEY}

# Create a schema
schema = {
    "name": "customers",
    "ddl": """CREATE TABLE customers (
        id SERIAL PRIMARY KEY,
        name VARCHAR(100),
        email VARCHAR(255),
        phone VARCHAR(20),
        created_at TIMESTAMP
    );"""
}
response = requests.post(f"{BASE_URL}/schemas", json=schema, headers=headers)
print(response.json())

# Generate data
response = requests.get(f"{BASE_URL}/generate/customers?rows=5", headers=headers)
customers = response.json()
print(f"Generated {len(customers)} customers:")
for customer in customers:
    print(customer)

Need Help?

Can't find what you're looking for? We're here to help.

Contact Support Get Started Free