{ "openapi": "3.0.3", "info": { "title": "LogicFlow Data Gen API", "version": "1.0.0", "description": "Generate deterministic sample data from a schema. Format CSV, TSV, or JSON. All responses use a seed, so a preview is always the prefix of a larger export." }, "servers": [ { "url": "/", "description": "This LogicFlow Data Gen instance" } ], "tags": [ { "name": "Data", "description": "Generate and preview datasets." }, { "name": "AI", "description": "Optional AI-assisted schema generation using a locally stored provider key." }, { "name": "Reference", "description": "Discover schema types and runtime limits." } ], "paths": { "/api/generate": { "post": { "tags": [ "Data" ], "summary": "Generate a dataset", "operationId": "generateDataset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateRequest" }, "example": { "rows": 1000, "format": "csv", "lineEnding": "crlf", "includeHeader": true, "bom": false, "seed": "MOCK-2401", "fields": [ { "key": "id", "type": "row_number", "blank": 0 }, { "key": "first_name", "type": "first_name", "blank": 0 }, { "key": "last_name", "type": "last_name", "blank": 0 }, { "key": "email", "type": "email", "blank": 0 }, { "key": "gender", "type": "gender", "blank": 0 }, { "key": "ip_address", "type": "ipv4", "blank": 0 } ] } } } }, "responses": { "200": { "description": "The generated file in the requested format.", "content": { "text/csv": { "schema": { "type": "string" } }, "text/tab-separated-values": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/preview": { "post": { "tags": [ "Data" ], "summary": "Preview a dataset", "description": "Returns the first 25 generated rows plus serialized output for the selected format.", "operationId": "previewDataset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateRequest" } } } }, "responses": { "200": { "description": "A preview of the dataset.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "columns", "meta", "raw" ], "properties": { "data": { "type": "array", "items": { "type": "object" } }, "columns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" } } } }, "meta": { "type": "object", "additionalProperties": true }, "raw": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/derive": { "post": { "tags": [ "Data" ], "summary": "Infer a schema from example data", "description": "Parse CSV, JSON, or XML example rows and infer field keys, supported field types, and blank rates. The returned fields can be sent directly to /api/generate.", "operationId": "deriveSchema", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeriveRequest" }, "example": { "format": "auto", "hasHeader": null, "data": "id,first_name,email,country\n1,Ada,ada@example.com,United Kingdom\n2,Grace,grace@example.com,United States" } } } }, "responses": { "200": { "description": "Inferred fields, a sample preview, and parse metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/InferredField" } }, "preview": { "type": "array", "items": { "type": "object" } }, "meta": { "type": "object", "additionalProperties": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/settings/ai": { "get": { "tags": [ "AI" ], "summary": "Read AI provider settings", "description": "Returns the provider, model, configured state, and a masked key hint. The raw key is never returned.", "operationId": "getAiSettings", "responses": { "200": { "description": "AI settings without the secret key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSettings" } } } } } }, "put": { "tags": [ "AI" ], "summary": "Save AI provider settings", "description": "Stores the key server-side in a local, gitignored settings file. Omit apiKey to keep the saved key.", "operationId": "saveAiSettings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSettingsUpdate" } } } }, "responses": { "200": { "description": "Saved AI settings with a masked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSettings" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "delete": { "tags": [ "AI" ], "summary": "Remove the stored API key", "operationId": "deleteAiSettings", "responses": { "200": { "description": "The key was removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSettings" } } } } } } }, "/api/settings/ai/test": { "post": { "tags": [ "AI" ], "summary": "Test an AI connection", "description": "Tests the saved connection or the provider values supplied in the request. Nothing is saved.", "operationId": "testAiConnection", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSettingsUpdate" } } } }, "responses": { "200": { "description": "The provider replied successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "provider": { "type": "string" }, "model": { "type": "string" }, "latencyMs": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "502": { "description": "The AI provider rejected the request or could not be reached." } } } }, "/api/ai/schema": { "post": { "tags": [ "AI" ], "summary": "Generate a schema with AI", "description": "Sends the prompt to the configured OpenAI-compatible provider and returns a validated LogicFlow Data Gen schema.", "operationId": "generateAiSchema", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSchemaRequest" } } } }, "responses": { "200": { "description": "A validated AI-proposed schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSchemaResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "502": { "description": "The AI provider rejected the request or could not be reached." }, "503": { "description": "No AI provider has been configured." } } } }, "/api/types": { "get": { "tags": [ "Reference" ], "summary": "List supported fields, formats, and limits", "operationId": "listTypes", "responses": { "200": { "description": "The field catalog and runtime limits.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/health": { "get": { "tags": [ "Reference" ], "summary": "Check API health", "operationId": "health", "responses": { "200": { "description": "Service status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "service": { "type": "string", "example": "logicflow-data-gen" }, "version": { "type": "string", "example": "1.0.0" }, "uptimeSeconds": { "type": "integer" } } } } } } } } }, "/api/openapi.json": { "get": { "tags": [ "Reference" ], "summary": "This OpenAPI document", "operationId": "openapi", "responses": { "200": { "description": "OpenAPI 3.0.3 specification.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Field": { "type": "object", "required": [ "key", "type" ], "properties": { "key": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "maxLength": 64, "example": "email", "description": "Column key and export header. Must be unique within the schema." }, "type": { "type": "string", "enum": [ "row_number", "uuid", "first_name", "last_name", "full_name", "username", "email", "gender", "date_of_birth", "phone", "company", "job_title", "department", "url", "domain", "street_address", "city", "state", "country", "postal_code", "ipv4", "ipv6", "latitude", "longitude", "product_name", "sku", "price", "currency", "order_status", "word", "sentence", "paragraph", "integer", "decimal", "boolean", "date", "datetime", "color" ], "example": "email" }, "blank": { "type": "number", "minimum": 0, "maximum": 100, "default": 0, "description": "Percentage of rows that should be left empty." } } }, "InferredField": { "type": "object", "properties": { "key": { "type": "string", "example": "email" }, "type": { "type": "string", "example": "email" }, "label": { "type": "string", "example": "Email Address" }, "blank": { "type": "number", "minimum": 0, "maximum": 100, "example": 0 }, "source": { "type": "string", "example": "Email Address" }, "sample": { "type": "array", "items": { "type": "string" } } } }, "DeriveRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "string", "maxLength": 200000, "description": "CSV, JSON, or XML example rows." }, "format": { "type": "string", "enum": [ "auto", "csv", "json", "xml" ], "default": "auto" }, "hasHeader": { "type": "boolean", "nullable": true, "description": "CSV header override. Omit or send null to auto-detect." } } }, "AiSettings": { "type": "object", "properties": { "configured": { "type": "boolean" }, "provider": { "type": "string", "enum": [ "openai", "openrouter", "custom" ] }, "providerLabel": { "type": "string" }, "baseUrl": { "type": "string", "format": "uri" }, "model": { "type": "string" }, "maskedKey": { "type": "string", "nullable": true, "example": "sk-…8f2d" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "AiSettingsUpdate": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "openrouter", "custom" ] }, "baseUrl": { "type": "string", "format": "uri", "example": "https://api.openai.com/v1" }, "model": { "type": "string", "example": "gpt-4.1-mini" }, "apiKey": { "type": "string", "writeOnly": true, "description": "Provider API key. Omit to keep an already-configured key." } } }, "AiSchemaRequest": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "minLength": 3, "maxLength": 800, "example": "A SaaS customer list for a fintech company with contact details and signup dates." } } }, "AiSchemaResponse": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/Field" } }, "meta": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" } } } } }, "GenerateRequest": { "type": "object", "required": [ "fields" ], "properties": { "fields": { "type": "array", "minItems": 1, "maxItems": 40, "items": { "$ref": "#/components/schemas/Field" } }, "rows": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1000 }, "seed": { "type": "string", "maxLength": 120, "default": "MOCK-2401", "description": "Any text. The same schema and seed always produce the same rows." }, "format": { "type": "string", "enum": [ "csv", "tsv", "json" ], "default": "csv" }, "lineEnding": { "type": "string", "enum": [ "crlf", "lf" ], "default": "crlf" }, "includeHeader": { "type": "boolean", "default": true }, "bom": { "type": "boolean", "default": false, "description": "Prefix CSV/TSV output with a UTF-8 byte order mark." } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "BadRequest": { "description": "The request could not be validated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }