API.md

API Documentation

REST API Endpoints

Base URL

http://localhost:5000

Authentication

Currently, the API is unauthenticated (for demo purposes).

---

Endpoints

1. Generate Configuration

Endpoint: POST /api/generate

Description: Generate a complete application configuration from a natural language prompt.

Request Body:

{
  "prompt": "Build a CRM with login, contacts, dashboard, and role-based access"
}

Query Parameters: None

Headers:

Content-Type: application/json

Response (Success):

{
  "success": true,
  "config": {
    "app_name": "CRM",
    "app_description": "...",
    "database_schema": [...],
    "api_schema": [...],
    "ui_schema": [...],
    "auth_config": {...},
    "roles": [...],
    "business_logic": {...}
  },
  "execution_log": {
    "timestamp": "2026-05-06T07:52:40.123456",
    "stages": {...}
  },
  "executable_report": {
    "is_executable": true,
    "errors": [],
    "warnings": [],
    "simulation_log": [...]
  },
  "is_executable": true
}

Response (Error):

{
  "success": false,
  "error": "Prompt is required"
}

Status Codes:

• 200: Successful generation
• 400: Bad request (invalid prompt)
• 500: Server error

Constraints:

• Prompt length: max 2,000 characters
• Rate limit: None (local deployment)

Example:

curl -X POST http://localhost:5000/api/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Build a todo app with users, tasks, and sharing"}'

---

2. Validate Configuration

Endpoint: POST /api/validate

Description: Validate an existing configuration against schema rules.

Request Body:

{
  "config": {
    "app_name": "MyApp",
    "app_description": "...",
    "database_schema": [...],
    ...
  }
}

Response (Success):

{
  "success": true,
  "is_executable": true,
  "report": {
    "is_executable": true,
    "errors": [],
    "warnings": [],
    "simulation_log": [
      "✓ Database table 'users' initialized",
      "✓ API endpoint 'GET /api/users' registered",
      ...
    ],
    "total_checks": 12
  }
}

Response (Error):

{
  "success": false,
  "error": "Internal server error"
}

Status Codes:

• 200: Validation complete (executable or not)
• 400: Bad request (invalid config)
• 500: Server error

---

3. Get Recent Requests

Endpoint: GET /api/recent

Description: Get list of recent generation requests (last 10).

Query Parameters: None

Response:

{
  "recent": [
    {
      "timestamp": "2026-05-06T07:52:40.123456",
      "prompt": "Build a CRM with login, contacts, dashboard...",
      "success": true,
      "executable": true
    },
    ...
  ]
}

Status Codes:

• 200: Success

---

4. Get Example Generation

Endpoint: GET /api/example

Description: Get a pre-generated example configuration.

Query Parameters: None

Response:

{
  "prompt": "Build a CRM with login, contacts, dashboard, role-based access...",
  "config": {...},
  "executable": true
}

Status Codes:

• 200: Success

---

5. Health Check

Endpoint: GET /api/health

Description: Check if the API is running and get system status.

Query Parameters: None

Response:

{
  "status": "healthy",
  "timestamp": "2026-05-06T07:52:40.123456",
  "total_requests": 15
}

Status Codes:

• 200: Healthy
• 503: Service unavailable

---

Error Responses

Common Error Codes

400 - Bad Request

{
  "error": "Prompt is required"
}

413 - Payload Too Large

{
  "error": "Prompt is too long (max 2000 chars)"
}

404 - Not Found

{
  "error": "Not found"
}

500 - Internal Server Error

{
  "error": "Internal server error"
}

---

Configuration Object Format

Top-Level Fields

{
  "app_name": "string",
  "app_description": "string",
  "database_schema": [...],
  "api_schema": [...],
  "ui_schema": [...],
  "auth_config": {...},
  "roles": [...],
  "business_logic": {...},
  "validation_metadata": {...}
}

Database Schema

{
  "name": "users",
  "fields": [
    {
      "name": "id",
      "type": "string",
      "required": true,
      "description": "User ID"
    },
    {
      "name": "email",
      "type": "email",
      "required": true,
      "validation_rules": {
        "unique": true
      }
    }
  ],
  "primary_key": "id",
  "relations": {
    "role_id": "roles"
  },
  "indexes": ["id", "email"]
}

API Schema

{
  "path": "/api/users",
  "method": "GET",
  "description": "Get list of users",
  "request_body": {
    "page": {
      "name": "page",
      "type": "number",
      "required": false
    }
  },
  "response_body": {
    "users": {
      "name": "users",
      "type": "array",
      "required": true
    }
  },
  "required_role": "user",
  "validation_rules": ["Pagination required", "Min page size: 10"]
}

UI Schema

{
  "path": "/users",
  "title": "Users Page",
  "components": [
    {
      "name": "header",
      "type": "header"
    },
    {
      "name": "user-table",
      "type": "table",
      "fields": ["id", "name", "email", "role"]
    }
  ],
  "required_role": "user",
  "data_source": "/api/users"
}

Auth Config

{
  "type": "jwt",
  "secret_key": "your-secret-key",
  "expiry": 3600,
  "refresh_token_expiry": 86400,
  "algorithm": "HS256"
}

Roles

[
  {
    "name": "admin",
    "permissions": ["read_all", "write_all", "delete_all", "manage_users"],
    "description": "Administrator with full access"
  },
  {
    "name": "user",
    "permissions": ["read_own", "write_own", "delete_own"],
    "description": "Regular user with personal access"
  }
]

---

Code Examples

Python (requests)

import requests
import json

# Generate configuration
response = requests.post(
    'http://localhost:5000/api/generate',
    json={
        'prompt': 'Build a CRM with contacts, dashboard, and analytics'
    }
)

config = response.json()

if config['success']:
    print(f"Generated: {config['config']['app_name']}")
    print(f"Executable: {config['is_executable']}")
    print(json.dumps(config['config'], indent=2))

JavaScript (fetch)

const prompt = "Build a CRM with contacts, dashboard, and analytics";

const response = await fetch('http://localhost:5000/api/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ prompt })
});

const data = await response.json();

if (data.success) {
  console.log('Generated:', data.config.app_name);
  console.log('Executable:', data.is_executable);
  console.log(JSON.stringify(data.config, null, 2));
}

cURL

# Generate config
curl -X POST http://localhost:5000/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Build a CRM with contacts, dashboard, and analytics"
  }' | jq .

# Health check
curl http://localhost:5000/api/health | jq .

# Get recent requests
curl http://localhost:5000/api/recent | jq .

# Get example
curl http://localhost:5000/api/example | jq .

---

Rate Limiting

Currently disabled. For production deployment, implement:

• 100 requests/minute per IP
• 10,000 requests/day per API key
• Exponential backoff on rate limit errors (429)

---

Webhooks (Future)

Support for event notifications:

• generation.started
• generation.completed
• generation.failed
• validation.warning

---

Version History

v1.0 (Current)

• Basic generation pipeline
• Validation and repair
• REST API
• Web interface

v1.1 (Planned)

• Advanced LLM selection
• Extended schema types
• Webhook support
• Rate limiting

v2.0 (Future)

• Direct app scaffolding
• Framework selection
• Deployment integration

---

Support

For API issues or questions:

1. Check ARCHITECTURE.md for system design
2. Review quickstart.py for examples
3. Run evaluation framework for diagnostics
4. Check execution logs in API responses