FloodGate REST API Reference

Base URL

http://localhost:5000

Authentication

Authentication is optional and configurable. When enabled:

X-API-Key: your-api-key

Response Format

All responses follow this structure:

{
  "success": true|false,
  "message": "Description of result",
  "data": { ... },
  "error": "Error details if success=false"
}

Rate Limiting

Default limits (configurable):

100 requests per minute per IP
10,000 documents per request
100MB max request size

Document Generator Endpoints

Health Check

Check API health status.

GET /api/documentgenerator/health

Response

{
  "status": "Healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0",
  "uptime": "00:15:30"
}

Status Codes

200 - Service is healthy
503 - Service unavailable

Generate Documents from Schema

Generate documents using an inline DataFlood schema.

POST /api/documentgenerator/generate-simple

Request Body

{
  "schema": {
    "type": "object",
    "properties": {
      "field1": {"type": "string"},
      "field2": {"type": "integer"}
    }
  },
  "count": 10,
  "seed": 12345,
  "format": "json",
  "includeMetadata": false,
  "entropyOverride": 2.5
}

Parameters

Field	Type	Required	Description	Default
schema	object	Yes	DataFlood schema	-
count	integer	No	Number of documents (1-10000)	1
seed	integer	No	Random seed	random
format	string	No	Output format (json/csv)	json
includeMetadata	boolean	No	Include generation metadata	false
entropyOverride	number	No	Override entropy (≥0)	schema default

Response

{
  "success": true,
  "generatedCount": 10,
  "documents": [...],
  "metadata": {
    "generatedAt": "2024-01-15T10:30:00Z",
    "seed": 12345,
    "format": "json",
    "generationTime": "00:00:00.150"
  },
  "message": "Successfully generated 10 documents"
}

Status Codes

200 - Success
400 - Invalid schema or parameters
500 - Server error

Generate from Uploaded File

Generate documents from an uploaded schema file.

POST /api/documentgenerator/generate-from-file

Request (multipart/form-data)

Field	Type	Required	Description	Default
schemaFile	file	Yes	DataFlood schema file	-
count	integer	No	Number of documents	1
seed	integer	No	Random seed	random
format	string	No	Output format	json
includeMetadata	boolean	No	Include metadata	false
entropyOverride	number	No	Entropy override	schema default

Example

curl -X POST "http://localhost:5000/api/documentgenerator/generate-from-file" \
  -F "schemaFile=@schema.json" \
  -F "count=100" \
  -F "format=csv"

Response

Same as generate-simple endpoint.

Test Endpoint

Test the document generator with a sample schema.

GET /api/documentgenerator/test

Response

{
  "success": true,
  "message": "Document generator is working",
  "sample": {
    "id": "TEST-123456",
    "name": "Test Document",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Serving Mode Endpoints

List Available Models

Get list of models in the Serving/Models directory.

GET /api/serving/models

Response

["CustomerModel", "ProductModel", "OrderModel", "TransactionModel"]

Status Codes

200 - Success
404 - Serving directory not found

Generate from Stored Model

Generate documents using a pre-stored model.

POST /api/serving/generate/{modelName}

Path Parameters

Parameter	Description
modelName	Name of model file (with or without .json)

Request Body

{
  "count": 100,
  "seed": 42,
  "format": "json",
  "entropyOverride": 2.5
}

Response

{
  "success": true,
  "modelName": "CustomerModel",
  "generatedCount": 100,
  "documents": [...],
  "message": "Successfully generated 100 documents from CustomerModel"
}

Status Codes

200 - Success
404 - Model not found
400 - Invalid parameters

Download Generated Documents

Generate and download documents as a file.

POST /api/serving/generate/{modelName}/download

Path Parameters

Parameter	Description
modelName	Name of model file

Request Body

Same as generate endpoint.

Response

Returns file download with appropriate content-type:

application/json for JSON
text/csv for CSV
application/x-ndjson for JSONL

List Available Tides

Get list of Tides in the Serving/Tides directory.

GET /api/serving/tides

Response

["DailyFlow", "PeakHours", "WeekendPattern", "MonthlyBatch"]

Execute Stored Tides

Execute a pre-stored Tides configuration.

POST /api/serving/tides/{tidesName}

Path Parameters

Parameter	Description
tidesName	Name of Tides file

Request Body

{
  "startTime": "2024-01-01T00:00:00Z",
  "endTime": "2024-01-01T23:59:59Z",
  "maxDocuments": 1000,
  "seed": 12345,
  "outputFormat": "json",
  "returnDocuments": true
}

Parameters

Field	Type	Required	Description	Default
startTime	datetime	No	Override start time	Tides config
endTime	datetime	No	Override end time	Tides config
maxDocuments	integer	No	Maximum documents	unlimited
seed	integer	No	Random seed	random
outputFormat	string	No	Output format	json
returnDocuments	boolean	No	Include documents	true

Response

{
  "success": true,
  "tidesName": "DailyFlow",
  "totalDocuments": 850,
  "documents": [...],
  "metadata": {
    "startTime": "2024-01-01T00:00:00Z",
    "endTime": "2024-01-01T23:59:59Z",
    "documentsByStep": {
      "step1": 300,
      "step2": 550
    },
    "executionTime": "00:00:05.230"
  }
}

Download Tides Results

Execute Tides and download results as file.

POST /api/serving/tides/{tidesName}/download

Parameters

Same as execute Tides endpoint.

Response

File download with Tides results.

Batch Generation

Generate from multiple models in one request.

POST /api/serving/batch/generate

Request Body

{
  "models": [
    {
      "modelName": "CustomerModel",
      "count": 100,
      "seed": 1
    },
    {
      "modelName": "ProductModel",
      "count": 200,
      "seed": 2
    }
  ],
  "includeDocuments": false,
  "outputFormat": "json"
}

Response

{
  "results": [
    {
      "modelName": "CustomerModel",
      "success": true,
      "documentCount": 100,
      "documents": [...] 
    },
    {
      "modelName": "ProductModel",
      "success": true,
      "documentCount": 200,
      "documents": [...]
    }
  ],
  "totalDocuments": 300,
  "successfulModels": 2,
  "failedModels": 0
}

Model Documentation Endpoints

List All Models

Get documentation for all available models.

GET /api/schemadocumentation/models

Response

[
  {
    "name": "CustomerModel",
    "fileName": "CustomerModel.json",
    "description": "Customer profile schema",
    "propertyCount": 15,
    "requiredProperties": ["customerId", "email"],
    "hasStringModels": true,
    "hasHistograms": true
  }
]

Get Model Details

Get detailed schema for a specific model.

GET /api/schemadocumentation/models/{modelName}

Response

{
  "name": "CustomerModel",
  "schema": {
    "type": "object",
    "properties": { ... }
  },
  "statistics": {
    "propertyCount": 15,
    "stringModelCount": 5,
    "histogramCount": 3
  }
}

List All Tides

Get documentation for all available Tides.

GET /api/schemadocumentation/tides

Response

[
  {
    "name": "DailyFlow",
    "fileName": "DailyFlow.json",
    "description": "Daily transaction flow",
    "stepCount": 5,
    "duration": "24:00:00",
    "hasTransactions": true
  }
]

Get Tides Details

Get detailed configuration for specific Tides.

GET /api/schemadocumentation/tides/{tidesName}

Response

{
  "name": "DailyFlow",
  "configuration": {
    "startTime": "2024-01-01T00:00:00Z",
    "endTime": "2024-01-01T23:59:59Z",
    "steps": [...],
    "transactions": [...]
  }
}

Get Overview

Get combined overview of all models and Tides.

GET /api/schemadocumentation/overview

Response

{
  "models": [...],
  "tides": [...],
  "statistics": {
    "totalModels": 15,
    "totalTides": 8,
    "totalProperties": 234
  }
}

Tides Endpoints

Execute Tides

Execute time-based document Tides.

POST /api/tides/execute

Request Body

{
  "configuration": {
    "name": "Test Tides",
    "startTime": "2024-01-01T00:00:00Z",
    "endTime": "2024-01-01T01:00:00Z",
    "intervalMs": 1000,
    "steps": [
      {
        "stepId": "step1",
        "modelPath": "./models/Model.json",
        "documentsPerInterval": 1,
        "generationProbability": 1.0
      }
    ],
    "transactions": []
  },
  "maxDocuments": 1000,
  "outputFormatOverride": "json",
  "seedOverride": 42,
  "validateOnly": false,
  "returnDocuments": true
}

Parameters

Field	Type	Required	Description
configuration	object	Yes	Tides configuration
maxDocuments	integer	No	Maximum documents
outputFormatOverride	string	No	Override format
seedOverride	integer	No	Override seed
validateOnly	boolean	No	Only validate
returnDocuments	boolean	No	Return documents

Response

{
  "success": true,
  "totalDocuments": 500,
  "documents": [...],
  "metadata": {
    "executionTime": "00:00:02.150",
    "documentsByStep": {
      "step1": 500
    }
  }
}

Validate Tides

Validate a Tides configuration without executing.

POST /api/tides/validate

Request Body

Tides configuration object.

Response

{
  "isValid": true,
  "errors": [],
  "warnings": [],
  "estimatedDocuments": 500
}

Error Responses

All endpoints may return error responses:

{
  "success": false,
  "error": "Detailed error message",
  "errorCode": "ERROR_CODE",
  "details": {
    "field": "Additional error context"
  }
}

Common Error Codes

Code	Description
INVALID_SCHEMA	Schema validation failed
MODEL_NOT_FOUND	Requested model doesn't exist
GENERATION_FAILED	Document generation error
INVALID_PARAMETERS	Request parameters invalid
QUOTA_EXCEEDED	Rate limit or size limit exceeded
INTERNAL_ERROR	Server error

HTTP Status Codes

Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - Access denied
404	Not Found - Resource doesn't exist
413	Payload Too Large
429	Too Many Requests - Rate limited
500	Internal Server Error
503	Service Unavailable

Request Headers

Required Headers

Content-Type: application/json

or for file uploads:

Content-Type: multipart/form-data

Optional Headers

X-API-Key: your-api-key
Accept: application/json
Accept-Encoding: gzip, deflate

Response Headers

Common response headers:

Content-Type: application/json
X-Request-Id: unique-request-id
X-Rate-Limit-Remaining: 95
X-Rate-Limit-Reset: 1642345678

Pagination

For endpoints that return large lists:

GET /api/endpoint?page=1&pageSize=100

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 100,
    "totalItems": 500,
    "totalPages": 5
  }
}

Versioning

API version is included in the URL path:

/api/v1/documentgenerator/generate

Current version: v1 (optional in URLs)

WebSocket Support

For real-time generation updates (if configured):

ws://localhost:5000/ws/generation

CORS Configuration

CORS is configurable in floodgate.config.yaml:

api:
  enableCors: true
  corsOrigins:
    - "http://localhost:3000"
    - "https://app.example.com"

Examples

cURL Examples

Generate with inline schema:

curl -X POST "http://localhost:5000/api/documentgenerator/generate-simple" \
  -H "Content-Type: application/json" \
  -d '{"schema": {...}, "count": 10}'

Upload and generate:

curl -X POST "http://localhost:5000/api/documentgenerator/generate-from-file" \
  -F "schemaFile=@schema.json" \
  -F "count=100"

Execute Tides:

curl -X POST "http://localhost:5000/api/tides/execute" \
  -H "Content-Type: application/json" \
  -d @tides-config.json

JavaScript/Fetch Examples

// Generate documents
const response = await fetch('http://localhost:5000/api/documentgenerator/generate-simple', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    schema: schemaObject,
    count: 50
  })
});
const result = await response.json();

Python Examples

import requests

## Generate from stored model
response = requests.post(
    'http://localhost:5000/api/serving/generate/CustomerModel',
    json={'count': 100, 'seed': 42}
)
data = response.json()