Prompt Improver API Documentation

Base URL: https://toowired--d1429bca8a6311f0be6e0224a6c84d84.web.val.run

POST /api/improve

Improves a single prompt using AI-powered workers.

Request:

{
  "prompt": "Write a function that calculates factorial"
}

Response:

{
  "result": "Create a Python function `calculate_factorial(n)` that computes...",
  "status": "working"
}

Status Codes:

• 200: Success
• 400: Invalid prompt
• 500: Server error

POST /api/improve/batch

Process multiple prompts in a single request.

Request:

{
  "prompts": [
    "Write a REST API",
    "Explain recursion",
    "Create a login form"
  ]
}

Response:

{
  "results": [
    {
      "original": "Write a REST API",
      "improved": "Design and implement a RESTful API...",
      "success": true
    }
  ],
  "totalProcessed": 3,
  "successCount": 3,
  "timestamp": "2024-01-01T12:00:00Z"
}

POST /api/improve/worker/:workerName

Use a specific worker for processing.

Valid Workers: clarifier, condenser, includer

Request:

{
  "prompt": "Make an app"
}

Response:

{
  "original": "Make an app",
  "improved": "Develop a mobile application that...",
  "worker": "clarifier",
  "processingTime": 8.5,
  "timestamp": "2024-01-01T12:00:00Z"
}

POST /api/analyze

Analyze a prompt's complexity and improvement potential.

Request:

{
  "prompt": "Write a function"
}

Response:

{
  "analysis": {
    "wordCount": 3,
    "characterCount": 16,
    "sentenceCount": 1,
    "averageWordLength": "5.3",
    "complexity": "Simple",
    "estimatedImprovementPotential": "High",
    "suggestedWorkers": ["includer", "clarifier"],
    "readabilityScore": 95
  },
  "recommendations": [
    "Your prompt is very short. Consider adding more context."
  ],
  "timestamp": "2024-01-01T12:00:00Z"
}

GET /api/stats

Retrieve usage statistics and analytics.

Response:

{
  "statistics": {
    "totalImproved": 8543,
    "averageProcessingTime": "34.2s",
    "averageWordIncrease": 127,
    "successRate": 98.5,
    "dailyUsage": 456,
    "weeklyUsage": 3192,
    "monthlyUsage": 13768
  },
  "popularPromptTypes": [
    {"type": "Function writing", "percentage": 35},
    {"type": "API documentation", "percentage": 25},
    {"type": "Marketing copy", "percentage": 20},
    {"type": "Technical explanations", "percentage": 15},
    {"type": "Other", "percentage": 5}
  ],
  "peakHours": [
    {"hour": "10:00", "usage": 450},
    {"hour": "14:00", "usage": 523},
    {"hour": "16:00", "usage": 412},
    {"hour": "20:00", "usage": 389}
  ],
  "timestamp": "2024-01-01T12:00:00Z"
}

GET /api/history

Retrieve past improvement history.

Query Parameters:

• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 20)

Response:

{
  "history": [
    {
      "id": 1234567890,
      "original": "Write a function",
      "improved": "Create a Python function that...",
      "timestamp": "2024-01-01T12:00:00Z",
      "wordCount": 45
    }
  ],
  "totalCount": 2,
  "page": 1,
  "limit": 20
}

POST /api/history

Save an improvement to history.

Request:

{
  "original": "Write a function",
  "improved": "Create a Python function that..."
}

Response:

{
  "success": true,
  "item": {
    "id": 1234567890,
    "original": "Write a function",
    "improved": "Create a Python function that...",
    "timestamp": "2024-01-01T12:00:00Z",
    "wordCount": 45
  },
  "message": "History saved successfully"
}

GET /api/workers/status

Get status of all AI workers.

Response:

{
  "workers": [
    {
      "name": "Clarifier",
      "status": "active",
      "description": "Makes prompts clearer and more specific",
      "lastActive": "2024-01-01T12:00:00Z",
      "processedCount": 543
    },
    {
      "name": "Condenser",
      "status": "active",
      "description": "Removes redundancy while maintaining clarity",
      "lastActive": "2024-01-01T12:00:00Z",
      "processedCount": 456
    },
    {
      "name": "Includer",
      "status": "active",
      "description": "Adds helpful context and details",
      "lastActive": "2024-01-01T12:00:00Z",
      "processedCount": 678
    }
  ],
  "totalProcessed": 1677,
  "uptime": "24h 35m",
  "lastCheck": "2024-01-01T12:00:00Z"
}

GET /health

Check system health and version.

Response:

{
  "status": "healthy",
  "project": "Prompt Improver",
  "version": "2.0.0",
  "architecture": "Val Town Projects",
  "workers": ["clarifier", "condenser", "includer"]
}

GET /api/test

Simple test endpoint to verify API connectivity.

Response:

{
  "status": "API working",
  "timestamp": "2024-01-01T12:00:00Z"
}

• Single Improve: 60 requests per minute
• Batch Improve: 10 requests per minute (max 10 prompts per batch)
• Analysis: 100 requests per minute
• Statistics: 300 requests per minute

All error responses follow this format:

{
  "error": "Error type",
  "message": "Detailed error message",
  "timestamp": "2024-01-01T12:00:00Z"
}

Currently, the API is public and doesn't require authentication. Future versions will support API keys for enhanced security and usage tracking.

curl -X POST https://toowired--d1429bca8a6311f0be6e0224a6c84d84.web.val.run/api/improve \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Write a Python function"}'

const response = await fetch('/api/improve', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: 'Write a Python function'
  })
});

const data = await response.json();
console.log(data.result);

import requests

response = requests.post(
  'https://toowired--d1429bca8a6311f0be6e0224a6c84d84.web.val.run/api/improve',
  json={'prompt': 'Write a Python function'}
)

data = response.json()
print(data['result'])

Future versions will support webhooks for async processing of large batches.

Real-time prompt improvement with live progress updates.