Data Studio Service API

The Data Studio Service provides AI-powered dataset management, schema versioning, scenario generation, and data binding capabilities.

Base URL (local): http://localhost:3009 Swagger UI: http://localhost:3009/api/docs

Overview

The Data Studio Service enables you to:

• Create and manage structured datasets
• Define and version data schemas
• Generate test scenarios with AI assistance
• Bind datasets to Sandbox simulations
• Analyze data usage and patterns
• Chat with AI about data generation strategies
• Share datasets across teams
• Import and export datasets in multiple formats

Authentication

All endpoints require a JWT Bearer token and are tenant-scoped. Include your token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Endpoints

Tag	Description
datasets	Dataset CRUD, list datasets, search
schemas	Schema definition, field types, validation rules
versions	Schema versioning, version comparison, rollback
scenarios	Test scenario generation, scenario templates
bindings	Bind datasets to Sandbox simulations, binding status
generation	AI-powered data generation, batch generation
analytics	Dataset usage metrics, field distribution analysis
chat	AI chat for data generation guidance (SSE streaming)
sharing	Share datasets with teams or publicly (no auth required for public)
locale	Locale-specific data generation (addresses, phone numbers, dates)
import-export	Import from CSV/JSON/YAML, export to multiple formats

Rate Limits

AI-powered features have tier-based rate limits:

Tier	Generation Requests	Chat Messages
Free	10/hour	20/hour
Pro	100/hour	100/hour
Enterprise	Unlimited	Unlimited

Key Features

AI-Powered Generation

The Data Studio uses AI to generate realistic test data based on your schema and context:

POST /data-studio/generation/generate

Request:

{
  "schemaId": "schema_abc123",
  "count": 50,
  "context": "E-commerce users with realistic purchase history",
  "locale": "en-US"
}

Response:

{
  "data": [
    {
      "id": "usr_001",
      "email": "alice.johnson@example.com",
      "createdAt": "2025-01-15T10:30:00Z",
      "totalOrders": 8,
      "lifetimeValue": 1243.56
    }
  ],
  "count": 50,
  "generationTime": 2.3
}

Schema Versioning

Track schema changes over time with automatic versioning:

POST /data-studio/versions

Request:

{
  "schemaId": "schema_abc123",
  "changes": [
    {
      "type": "field_added",
      "field": "phone_verified",
      "fieldType": "boolean"
    }
  ],
  "description": "Added phone verification field"
}

Dataset Bindings

Bind datasets to Sandbox simulations for dynamic mock responses:

POST /data-studio/bindings

Request:

{
  "datasetId": "ds_xyz789",
  "simulationId": "sim_abc123",
  "routePath": "/api/users",
  "responseTemplate": "{{dataset.users | sample}}"
}

AI Chat (SSE Streaming)

Get real-time AI guidance for data generation strategies:

GET /data-studio/chat/stream?message=How+do+I+generate+realistic+addresses

Response (SSE stream):

event: message
data: {"role": "assistant", "content": "For realistic addresses, you can use..."}

event: done
data: {"complete": true}

Public Sharing

Share datasets without authentication:

GET /data-studio/sharing/public/:shareToken

This endpoint does not require authentication. Anyone with the share token can access the dataset.

Common Workflows

Create a Dataset with Schema

1. Define schema:

   POST /data-studio/schemas

2. Create dataset:

   POST /data-studio/datasets

3. Generate data:

   POST /data-studio/generation/generate

4. Bind to simulation:

   POST /data-studio/bindings

Version a Schema Change

1. Update schema fields:

   PATCH /data-studio/schemas/:id

2. Create version:

   POST /data-studio/versions

3. Compare versions:

   GET /data-studio/versions/compare?from=v1&to=v2

Export Dataset for Testing

1. Export to JSON:

   GET /data-studio/import-export/export/:datasetId?format=json

2. Use in CI/CD:

   curl -H "Authorization: Bearer $TOKEN" \
     "https://api.surestage.com/data-studio/import-export/export/ds_xyz789?format=json" \
     -o test-data.json

Error Codes

Status	Code	Meaning
400	INVALID_SCHEMA	Schema validation failed
400	GENERATION_FAILED	AI generation request failed
404	DATASET_NOT_FOUND	Dataset does not exist
409	BINDING_CONFLICT	Route already has a binding
429	RATE_LIMIT_EXCEEDED	Tier limit reached for AI features

Examples

Create Dataset with Schema

curl -X POST https://api.surestage.com/data-studio/datasets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User Profiles",
    "description": "Test users for signup flow",
    "schema": {
      "fields": [
        {"name": "email", "type": "email", "required": true},
        {"name": "age", "type": "integer", "min": 18, "max": 100},
        {"name": "country", "type": "string", "enum": ["US", "CA", "UK"]}
      ]
    }
  }'

Generate Data with AI

curl -X POST https://api.surestage.com/data-studio/generation/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schemaId": "schema_abc123",
    "count": 100,
    "context": "Enterprise SaaS users with varied subscription tiers",
    "locale": "en-US"
  }'

Stream AI Chat

curl -N -H "Authorization: Bearer $TOKEN" \
  "https://api.surestage.com/data-studio/chat/stream?message=Generate+realistic+order+data"

Share Dataset Publicly

curl -X POST https://api.surestage.com/data-studio/sharing \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "datasetId": "ds_xyz789",
    "visibility": "public",
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

Response:

{
  "shareToken": "sh_abc123def456",
  "publicUrl": "https://api.surestage.com/data-studio/sharing/public/sh_abc123def456"
}

Related

• Data Studio Overview - User guide for Data Studio
• AI Features - AI capabilities in SureStage
• Data Studio Service Architecture - Service internals

OpenAPI Spec

When the platform is running locally, access the interactive Swagger UI at localhost:3009/api/docs.

Auto-generated API docs from the OpenAPI spec will appear in this section once exported.