API Hub & Documentation

0. /test

Simple API key validation endpoint.

Method: GET
Headers: X-API-Key

1. /account/status

Check the status of your API key and see the remaining credit balance on your associated account.

Method: GET
Headers: X-API-Key

Success Response (200 OK)

{
  "api_key_status": "active",
  "business_name": "Your Business Name",
  "credits_remaining": 985
}

Note: credits_remaining will show -1 for unlimited credits.

cURL Example

curl -X GET 'https://feedbackflows.org/api/v1/account/status' -H 'X-API-Key: YOUR_API_KEY_HERE'

Python Example

import requests

api_key = "YOUR_API_KEY_HERE"
url = "https://feedbackflows.org/api/v1/account/status"
headers = {"X-API-Key": api_key}

response = requests.get(url, headers=headers)
if response.status_code == 200:
    print("Success:", response.json())
else:
    print("Error:", response.status_code, response.text)

2. /interactive-feedback

Generate structured, AI-powered feedback based on specific marking criteria.

Method: POST
Headers: X-API-Key, Content-Type: application/json

Request Body

{
  "student_text": "The student's full essay or text goes here.",
  "marking_criteria": [
    "Clarity of argument",
    "Use of evidence"
  ]
}

Success Response (200 OK)

{
  "feedback_breakdown": [
    {
      "criterion": "Clarity of argument",
      "feedback": "The main argument is identifiable, but it gets lost in the second paragraph.",
      "suggestion": "Try to start each paragraph with a clear topic sentence.",
      "confidence_score": 0.95
    }
  ]
}

cURL Example

curl -X POST 'https://feedbackflows.org/api/v1/interactive-feedback' \
-H 'X-API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
  "student_text": "The industrial revolution was a pivotal moment in history.",
  "marking_criteria": ["Introduction", "Historical Accuracy"]
}'

3. /smart-essay-marker

Automatically mark a full essay, providing detailed qualitative feedback broken down by each criterion.

Method: POST
Headers: X-API-Key, Content-Type: application/json

Request Body

{
  "essay_text": "The full text of the student's essay.",
  "marking_criteria": [
    "Clarity of argument",
    "Use of evidence"
  ]
}

Success Response (200 OK)

{
  "overall_recommendations": "This is a promising draft. The main areas for improvement are strengthening the evidence and ensuring the conclusion directly summarizes the key points discussed.",
  "referencing_note": "Remember to use a consistent citation style throughout the work.",
  "criteria_feedback": [
    {
      "criterion": "Use of evidence",
      "assessment": "Not Met",
      "how_it_was_met": "The essay currently relies on general statements without specific support.",
      "quoted_sentence": "While it connects us, it can also create distance.",
      "areas_for_improvement": "Incorporate data, studies, or specific examples to substantiate your claims."
    }
  ]
}

cURL Example

curl -X POST 'https://feedbackflows.org/api/v1/smart-essay-marker' \
-H 'X-API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
  "essay_text": "The entire essay text goes here...",
  "marking_criteria": ["Assess the use of historical evidence"]
}'

4. /ai-tutor

Provide formative, structured feedback on a student's draft with selectable tutor personas.

Method: POST
Headers: X-API-Key, Content-Type: application/json

Request Body

{
  "student_draft": "The student's draft text.",
  "mode": "general",
  "persona": "encouraging"
}

Note: persona is optional ("encouraging" or "direct"). mode can be "general" or "rubric".

Success Response (200 OK)

{
  "feedback_points": [
    {
      "topic": "Clarity",
      "feedback": "This sentence is a great start! To make it even stronger, you could use more descriptive language.",
      "suggestion": "Instead of 'some issues', you could specify what they are, for example: 'our plan has some logistical and budgetary issues.'",
      "quote": "our plan has some issues"
    }
  ]
}

cURL Example

curl -X POST 'https://feedbackflows.org/api/v1/ai-tutor' \
-H 'X-API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
  "student_draft": "The industrial revolution was very important.",
  "mode": "general",
  "persona": "direct"
}'

5. /reference-check (AI Content Detector)

Analyzes a document to assess the likelihood of it being AI-generated.

Method: POST
Headers: X-API-Key, Content-Type: application/json

Request Body

{
  "document_text": "The document content to be analyzed."
}

Success Response (200 OK)

{
  "ai_probability_score": 0.88,
  "highlighted_sentences": [
    "The intricate tapestry of modern society is woven with the threads of technological advancement."
  ],
  "summary": "The text shows strong indicators of AI generation, particularly in its sentence structure."
}

cURL Example

curl -X POST 'https://feedbackflows.org/api/v1/reference-check' \
-H 'X-API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
  "document_text": "The theory of constructive alignment is a cornerstone of modern pedagogical design..."
}'

5b. /ai-detector

Hybrid AI detector endpoint with detailed scoring output.

Method: POST
Headers: X-API-Key, Content-Type: application/json

Request Body

{
  "document_text": "The document content to be analyzed."
}

6. /full-reference-check

A comprehensive tool to validate reference formatting and (optionally) check for semantic alignment.

Method: POST
Headers: X-API-Key, Content-Type: application/json

Request Body

{
  "document_text": "The full text of the document, including in-text citations and a bibliography.",
  "style": "APA",
  "enable_semantic_check": true
}

Note: Supported style values are "APA", "Harvard", "MLA", and "Chicago".

Success Response (200 OK)

{
  "citation_analysis": {
    "style_used": "APA",
    "in_text_citation_count": 3,
    "reference_list_count": 2,
    "matched_references": [ "Smith, 2020" ],
    "unmatched_in_text_citations": [ "Jones, 2019", "Williams, 2021" ]
  },
  "semantic_analysis": [
    {
      "citation": "(Smith, 2020)",
      "student_argument_context": "According to Smith (2020), the results were conclusive.",
      "analysis": {
        "ok": true,
        "rationale": "The source likely discusses conclusive results, aligning with the student's claim.",
        "suggested_action": "Ensure the specific details from the source are accurately represented.",
        "confidence": 0.9
      }
    }
  ]
}

cURL Example

curl -X POST 'https://feedbackflows.org/api/v1/full-reference-check' \
-H 'X-API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
  "document_text": "The theory of constructive alignment... (Biggs, 2014). References: Biggs, J. (2014)...",
  "style": "APA",
  "enable_semantic_check": true
}'

7. /batch-style/jobs

Create a style-comparison batch job from a base64-encoded ZIP file of submissions.

Method: POST
Headers: X-API-Key, Content-Type: application/json

Request Body

{
  "filename": "submissions.zip",
  "zip_base64": "BASE64_ZIP_CONTENT"
}

Success Response (202 Accepted)

{
  "job_id": 123,
  "status": "QUEUED",
  "estimated_cost_if_all_files_processed": 12,
  "status_endpoint": "/api/v1/batch-style/jobs/123"
}

8. /batch-style/jobs/<job_id>

Get batch style job status, completed comparisons, and unmatched files.

Method: GET
Headers: X-API-Key

9. /rubric-marking/jobs

Create a rubric-based batch marking job with a base64 ZIP and an existing rubric.

Method: POST
Headers: X-API-Key, Content-Type: application/json

Request Body

{
  "rubric_id": 45,
  "filename": "class_work.zip",
  "marking_style": "simple",
  "grading_system": "pmd",
  "zip_base64": "BASE64_ZIP_CONTENT"
}

10. /rubric-marking/jobs/<job_id>

Get rubric marking job status and per-student feedback output.

Method: GET
Headers: X-API-Key

11. /automarking/jobs

Create an automated marking job with structured questions plus a base64 ZIP of student submissions.

Method: POST
Headers: X-API-Key, Content-Type: application/json

Request Body

{
  "questions": [
    {
      "question_text": "Explain TCP/IP.",
      "available_marks": 6,
      "mark_scheme": "Mentions layers, protocols, and role in networking."
    }
  ],
  "zip_base64": "BASE64_ZIP_CONTENT",
  "mark_mode": "Both",
  "flexible_marking": false,
  "bypass_automark_cache": false,
  "automarking_consistency_mode": "standard"
}

12. /automarking/jobs/<job_id>

Get automarking job status, progress, and per-result data.

Method: GET
Headers: X-API-Key

13. /students/<student_id>/ai-history

Retrieve AI detection history in chart-ready format for a student.

Method: GET
Headers: X-API-Key

Optional Query Params: start=YYYY-MM-DD, end=YYYY-MM-DD

14. /students/<student_id>/progress-report

Generate an AI-written progress report from marking history.

Method: POST
Headers: X-API-Key, Content-Type: application/json

Request Body

{
  "start_date": "2026-01-01",
  "end_date": "2026-03-31"
}

15. /classes/<class_id>/assignments/<assignment_id>/analyze

Generate class-level assignment analysis from existing marking feedback.

Method: POST
Headers: X-API-Key

16. /students/<student_id>/worksheet

Generate a personalized worksheet from supplied weaknesses or prior marking history.

Method: POST
Headers: X-API-Key, Content-Type: application/json

Request Body

{
  "weaknesses_list": ["Citation structure", "Paragraph cohesion"],
  "format": "short_answer",
  "level": "Intermediate",
  "num_questions": 5
}

17. /stats/users (Admin)

Admin-only endpoint that returns total user count.

Method: GET
Headers: X-API-Key (admin key)