API_FORMAT_DOCUMENTATION.md

Essay Analysis API - Exact JSON Format

API Endpoints Overview

This API provides comprehensive essay analysis with the exact JSON format required by the web development team.

Available Endpoints

1. /api/essay-analysis - Comprehensive essay analysis (supports optional question parameter)
2. /api/essay-analysis-with-question - NEW Comprehensive essay analysis based on a specific question
3. /api/feedback - Feedback generation (supports optional question parameter)
4. /api/feedback-with-question - NEW Feedback generation based on a specific question

Updated API Endpoint: /api/essay-analysis

This endpoint now supports an optional question parameter for question-specific analysis.

Request

• Method: POST
• Content-Type: application/x-www-form-urlencoded
• Body:
  • essay_text=<your_essay_text> (required)
  • question=<your_specific_question> (optional)

Response Format

The API returns a JSON object with the following exact structure:

When no question is provided (general analysis):

{
  "originalEssayWordCount": 300,
  "reWrittenEssayWordCount": 300,
  "originalEssay": "Your original essay text here...",
  "reWrittenEssay": "Your rewritten essay text here...",
  "overallEssayEvaluationScore": 70,
  "analysisType": "general",
  "evaluationAndScoring": [
    {
      "label": "Grammar & Punctuation",
      "score": 70,
      "analysis": "Detailed analysis of grammar and punctuation",
      "issuesCount": 2,
      "issuesList": [
        {
          "before": "Original text with error",
          "after": "Corrected text",
          "explanation": "Why this change is needed"
        }
      ],
      "positivePoints": ["Specific examples of good grammar usage"]
    }
  ],
  "essayStructure": [
    {
      "label": "Introduction & Thesis",
      "features": [
        {
          "label": "Clear Thesis Statement",
          "isCorrect": true
        },
        {
          "label": "Engaging Introduction",
          "isCorrect": false,
          "errorMessage": "Introduction should be more engaging and capture reader's attention."
        }
      ]
    }
  ],
  "topicSpecificFeedback": {
    "topicCoverage": "Detailed analysis of how well the topic is addressed",
    "missingAspects": ["Aspects that could be better covered"],
    "strengths": ["Specific strengths in topic handling"],
    "improvementSuggestions": ["Specific suggestions for better topic coverage"]
  }
}

When a question is provided (question-specific analysis):

{
  "originalEssayWordCount": 300,
  "reWrittenEssayWordCount": 300,
  "originalEssay": "Your original essay text here...",
  "reWrittenEssay": "Your rewritten essay text here...",
  "overallEssayEvaluationScore": 70,
  "analysisType": "question_specific",
  "question": "Your specific question here...",
  "questionSpecificFeedback": {
    "question": "Your specific question here...",
    "question_relevance_score": 85,
    "question_coverage": "Detailed analysis of how well the question is addressed",
    "covered_aspects": ["Specific aspects of the question that are well covered"],
    "missing_aspects": ["Aspects of the question that are missing or poorly addressed"],
    "strengths": ["Specific strengths in addressing the question"],
    "improvement_suggestions": ["Specific suggestions for better question coverage"]
  },
  "evaluationAndScoring": [
    {
      "label": "Grammar & Punctuation",
      "score": 70,
      "analysis": "Detailed analysis of grammar and punctuation",
      "issuesCount": 2,
      "issuesList": [
        {
          "before": "Original text with error",
          "after": "Corrected text",
          "explanation": "Why this change is needed"
        }
      ],
      "positivePoints": ["Specific examples of good grammar usage"]
    }
  ],
  "essayStructure": [
    {
      "label": "Introduction & Thesis",
      "features": [
        {
          "label": "Clear Thesis Statement",
          "isCorrect": true
        },
        {
          "label": "Engaging Introduction",
          "isCorrect": false,
          "errorMessage": "Introduction should be more engaging and capture reader's attention."
        }
      ]
    }
  ]
}

Updated API Endpoint: /api/feedback

This endpoint now supports an optional question parameter for question-specific feedback.

Request

• Method: POST
• Content-Type: application/x-www-form-urlencoded
• Body:
  • essay_text=<your_essay_text> (required)
  • question=<your_specific_question> (optional)

Response Format

When no question is provided (general feedback):

{
  "feedback": {
    "sections": [
      {
        "name": "Grammar & Punctuation",
        "score": 85,
        "analysis": "Detailed analysis of grammar and punctuation",
        "issues": [
          {
            "before": "Original text with error",
            "after": "Corrected text",
            "explanation": "Why this change is needed"
          }
        ],
        "positive_points": ["Specific examples of good grammar usage"],
        "issues_count": 1
      }
    ],
    "overall_score": 82,
    "essay_structure": {
      "Introduction & Thesis": {
        "Clear Thesis Statement": {
          "value": true,
          "explanation": "Thesis is clearly stated",
          "suggestions": "Consider strengthening the thesis"
        }
      }
    }
  },
  "feedback_type": "general",
  "question": null,
  "pdf_path": "/path/to/generated/pdf"
}

When a question is provided (question-specific feedback):

{
  "feedback": {
    "sections": [
      {
        "name": "Grammar & Punctuation",
        "score": 85,
        "analysis": "Detailed analysis of grammar and punctuation",
        "issues": [
          {
            "before": "Original text with error",
            "after": "Corrected text",
            "explanation": "Why this change is needed"
          }
        ],
        "positive_points": ["Specific examples of good grammar usage"],
        "issues_count": 1
      }
    ],
    "overall_score": 82,
    "essay_structure": {
      "Introduction & Thesis": {
        "Clear Thesis Statement": {
          "value": true,
          "explanation": "Thesis is clearly stated",
          "suggestions": "Consider strengthening the thesis"
        }
      }
    },
    "question_specific_feedback": {
      "question": "Your specific question here...",
      "question_relevance_score": 85,
      "question_coverage": "Detailed analysis of how well the question is addressed",
      "covered_aspects": ["Specific aspects of the question that are well covered"],
      "missing_aspects": ["Aspects of the question that are missing or poorly addressed"],
      "strengths": ["Specific strengths in addressing the question"],
      "improvement_suggestions": ["Specific suggestions for better question coverage"]
    }
  },
  "feedback_type": "question_specific",
  "question": "Your specific question here...",
  "pdf_path": "/path/to/generated/pdf"
}

New API Endpoint: /api/essay-analysis-with-question

This endpoint provides comprehensive essay analysis with the exact JSON format required by the web development team, but now includes question-specific evaluation.

Request

• Method: POST
• Content-Type: application/x-www-form-urlencoded
• Body:
  • essay_text=<your_essay_text>
  • question=<your_specific_question>

Response Format

The API returns a JSON object with the following exact structure:

{
  "originalEssayWordCount": 300,
  "reWrittenEssayWordCount": 300,
  "originalEssay": "Your original essay text here...",
  "reWrittenEssay": "Your rewritten essay text here...",
  "overallEssayEvaluationScore": 70,
  "question": "Your specific question here...",
  "questionSpecificFeedback": {
    "question": "Your specific question here...",
    "question_relevance_score": 85,
    "question_coverage": "Detailed analysis of how well the question is addressed",
    "covered_aspects": ["Specific aspects of the question that are well covered"],
    "missing_aspects": ["Aspects of the question that are missing or poorly addressed"],
    "strengths": ["Specific strengths in addressing the question"],
    "improvement_suggestions": ["Specific suggestions for better question coverage"]
  },
  "evaluationAndScoring": [
    {
      "label": "Grammar & Punctuation",
      "score": 70,
      "analysis": "Detailed analysis of grammar and punctuation",
      "issuesCount": 2,
      "issuesList": [
        {
          "before": "Original text with error",
          "after": "Corrected text",
          "explanation": "Why this change is needed"
        }
      ],
      "positivePoints": ["Specific examples of good grammar usage"]
    },
    {
      "label": "Vocabulary Usage",
      "score": 75,
      "analysis": "Detailed analysis of vocabulary usage",
      "issuesCount": 1,
      "issuesList": [
        {
          "before": "Original word/phrase",
          "after": "Improved word/phrase",
          "explanation": "Why this improvement is suggested"
        }
      ],
      "positivePoints": ["Specific examples of good vocabulary usage"]
    },
    {
      "label": "Sentence Structure",
      "score": 100,
      "analysis": "Detailed analysis of sentence structure",
      "issuesCount": 0,
      "issuesList": [],
      "positivePoints": ["Specific examples of good sentence structure"]
    }
  ],
  "essayStructure": [
    {
      "label": "Introduction & Thesis",
      "features": [
        {
          "label": "Clear Thesis Statement",
          "isCorrect": true
        },
        {
          "label": "Engaging Introduction",
          "isCorrect": false,
          "errorMessage": "Introduction should be more engaging and capture reader's attention."
        },
        {
          "label": "Background Context",
          "isCorrect": true
        }
      ]
    },
    {
      "label": "Body Development",
      "features": [
        {
          "label": "Topic Sentences",
          "isCorrect": true
        },
        {
          "label": "Supporting Evidence",
          "isCorrect": true
        },
        {
          "label": "Logical Flow",
          "isCorrect": true
        },
        {
          "label": "Paragraph Coherence",
          "isCorrect": true
        }
      ]
    },
    {
      "label": "Content Quality",
      "features": [
        {
          "label": "Relevance to Topic",
          "isCorrect": true
        },
        {
          "label": "Depth of Analysis",
          "isCorrect": false,
          "errorMessage": "Analysis could be deeper with more critical examination of the topic."
        },
        {
          "label": "Use of Examples",
          "isCorrect": true
        },
        {
          "label": "Critical Thinking",
          "isCorrect": true
        }
      ]
    },
    {
      "label": "Evidence & Citations",
      "features": [
        {
          "label": "Factual Accuracy",
          "isCorrect": true
        },
        {
          "label": "Source Credibility",
          "isCorrect": true
        },
        {
          "label": "Proper Citations",
          "isCorrect": false,
          "errorMessage": "Citations should follow proper academic format."
        },
        {
          "label": "Statistical Data",
          "isCorrect": true
        }
      ]
    },
    {
      "label": "Conclusion",
      "features": [
        {
          "label": "Summary of Arguments",
          "isCorrect": true
        },
        {
          "label": "Policy Recommendations",
          "isCorrect": true
        },
        {
          "label": "Future Implications",
          "isCorrect": true
        },
        {
          "label": "Strong Closing",
          "isCorrect": true
        }
      ]
    }
  ]
}

New API Endpoint: /api/feedback-with-question

This endpoint provides detailed feedback based on a specific question.

Request

• Method: POST
• Content-Type: application/x-www-form-urlencoded
• Body:
  • essay_text=<your_essay_text>
  • question=<your_specific_question>

Response Format

{
  "feedback": {
    "sections": [
      {
        "name": "Grammar & Punctuation",
        "score": 85,
        "analysis": "Detailed analysis of grammar and punctuation",
        "issues": [
          {
            "before": "Original text with error",
            "after": "Corrected text",
            "explanation": "Why this change is needed"
          }
        ],
        "positive_points": ["Specific examples of good grammar usage"],
        "issues_count": 1
      }
    ],
    "overall_score": 82,
    "essay_structure": {
      "Introduction & Thesis": {
        "Clear Thesis Statement": {
          "value": true,
          "explanation": "Thesis is clearly stated",
          "suggestions": "Consider strengthening the thesis"
        }
      }
    },
    "question_specific_feedback": {
      "question": "Your specific question here...",
      "question_relevance_score": 85,
      "question_coverage": "Detailed analysis of how well the question is addressed",
      "covered_aspects": ["Specific aspects of the question that are well covered"],
      "missing_aspects": ["Aspects of the question that are missing or poorly addressed"],
      "strengths": ["Specific strengths in addressing the question"],
      "improvement_suggestions": ["Specific suggestions for better question coverage"]
    }
  },
  "question": "Your specific question here...",
  "pdf_path": "/path/to/generated/pdf"
}

Field Descriptions

Top-level Fields (for essay-analysis-with-question)

• originalEssayWordCount (integer): Number of words in the original essay
• reWrittenEssayWordCount (integer): Number of words in the rewritten essay
• originalEssay (string): The original essay text submitted by the user
• reWrittenEssay (string): The AI-improved version of the essay
• overallEssayEvaluationScore (integer): Overall score from 0-100
• question (string): The specific question that was evaluated (only when question is provided)
• questionSpecificFeedback (object): Detailed feedback on how well the essay addresses the question (only when question is provided)
• evaluationAndScoring (array): Detailed evaluation in multiple categories
• essayStructure (array): Essay structure analysis
• analysisType (string): Either "general" or "question_specific"

questionSpecificFeedback Object

• question (string): The specific question being evaluated
• question_relevance_score (integer): Score from 0-100 indicating how well the essay addresses the question
• question_coverage (string): Detailed analysis of question coverage
• covered_aspects (array): List of question aspects that are well covered
• missing_aspects (array): List of question aspects that are missing or poorly addressed
• strengths (array): List of strengths in addressing the question
• improvement_suggestions (array): List of suggestions for better question coverage

evaluationAndScoring Array

Each item contains:

• label (string): Category name
• score (integer): Score from 0-100 for this category
• analysis (string): Detailed analysis of the category
• issuesCount (integer): Number of issues found
• issuesList (array): List of specific issues with before/after corrections and explanations
• positivePoints (array): List of positive aspects in this category

essayStructure Array

Each item contains:

• label (string): Structure category name
• features (array): List of features evaluated in this category
  • label (string): Feature name
  • isCorrect (boolean): Whether the feature is correct
  • errorMessage (string, optional): Error message if isCorrect is false

Example Usage

Testing the Updated Endpoints

import requests

# Test the updated essay analysis endpoint without question
response = requests.post(
    "http://localhost:8000/api/essay-analysis",
    data={"essay_text": "Your essay text here..."},
    headers={"Content-Type": "application/x-www-form-urlencoded"}
)

if response.status_code == 200:
    result = response.json()
    print(f"Overall Score: {result['overallEssayEvaluationScore']}")
    print(f"Analysis Type: {result['analysisType']}")

# Test the updated essay analysis endpoint with question
response = requests.post(
    "http://localhost:8000/api/essay-analysis",
    data={
        "essay_text": "Your essay text here...",
        "question": "Discuss the impact of climate change on global economies."
    },
    headers={"Content-Type": "application/x-www-form-urlencoded"}
)

if response.status_code == 200:
    result = response.json()
    print(f"Overall Score: {result['overallEssayEvaluationScore']}")
    print(f"Question: {result['question']}")
    print(f"Question Relevance Score: {result['questionSpecificFeedback']['question_relevance_score']}")
    print(f"Analysis Type: {result['analysisType']}")

# Test the updated feedback endpoint without question
response = requests.post(
    "http://localhost:8000/api/feedback",
    data={"essay_text": "Your essay text here..."},
    headers={"Content-Type": "application/x-www-form-urlencoded"}
)

if response.status_code == 200:
    result = response.json()
    print(f"Feedback Type: {result['feedback_type']}")
    print(f"Overall Score: {result['feedback']['overall_score']}")

# Test the updated feedback endpoint with question
response = requests.post(
    "http://localhost:8000/api/feedback",
    data={
        "essay_text": "Your essay text here...",
        "question": "Analyze the role of technology in modern education."
    },
    headers={"Content-Type": "application/x-www-form-urlencoded"}
)

if response.status_code == 200:
    result = response.json()
    print(f"Feedback Type: {result['feedback_type']}")
    print(f"Question: {result['question']}")
    print(f"Question Relevance Score: {result['feedback']['question_specific_feedback']['question_relevance_score']}")

Testing the New Question-Specific Endpoint

import requests

# Test the new question-specific API
response = requests.post(
    "http://localhost:8000/api/essay-analysis-with-question",
    data={
        "essay_text": "Your essay text here...",
        "question": "Discuss the impact of climate change on global economies."
    },
    headers={"Content-Type": "application/x-www-form-urlencoded"}
)

if response.status_code == 200:
    result = response.json()
    print(f"Overall Score: {result['overallEssayEvaluationScore']}")
    print(f"Question: {result['question']}")
    print(f"Question Relevance Score: {result['questionSpecificFeedback']['question_relevance_score']}")
    print(f"Original Word Count: {result['originalEssayWordCount']}")
    print(f"Rewritten Word Count: {result['reWrittenEssayWordCount']}")

Testing the Feedback with Question Endpoint

import requests

# Test the feedback with question API
response = requests.post(
    "http://localhost:8000/api/feedback-with-question",
    data={
        "essay_text": "Your essay text here...",
        "question": "Analyze the role of technology in modern education."
    },
    headers={"Content-Type": "application/x-www-form-urlencoded"}
)

if response.status_code == 200:
    result = response.json()
    print(f"Question: {result['question']}")
    print(f"Overall Score: {result['feedback']['overall_score']}")
    print(f"Question Relevance Score: {result['feedback']['question_specific_feedback']['question_relevance_score']}")

Testing

Run the test script to verify the API format:

python test_api_format.py

This will test all endpoints including the updated existing endpoints and new question-specific ones and save the full responses to JSON files for inspection.

Key Differences Between Endpoints

1. Updated Existing Endpoints (/api/essay-analysis, /api/feedback):

   • Accept optional question parameter
   • Provide general analysis/feedback when no question is provided
   • Provide question-specific analysis/feedback when question is provided
   • Include analysisType or feedback_type field to indicate the type of analysis
   • Backward compatible with existing implementations

2. New Question-Specific Endpoints (/api/essay-analysis-with-question, /api/feedback-with-question):

   • Require both essay_text and question parameters
   • Always provide question-specific analysis and feedback
   • Include question relevance scoring
   • Focus on how well the essay addresses the specific question
   • Provide detailed feedback on question coverage and missing aspects