openapi: 3.0.3
info:
  title: Feedback Flows API
  version: "1.0"
  description: Programmatic access to Feedback Flows marking, feedback, and integrity tools.
  contact:
    url: https://feedbackflows.org/contact
servers:
  - url: https://feedbackflows.org/api/v1
security:
  - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
paths:
  /test:
    get:
      summary: Validate API key
      responses:
        "200":
          description: Key is valid
  /account/status:
    get:
      summary: Account status and credits
      responses:
        "200":
          description: Status payload
  /interactive-feedback:
    post:
      summary: Interactive feedback by criteria
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [student_text, marking_criteria]
              properties:
                student_text:
                  type: string
                marking_criteria:
                  type: array
                  items:
                    type: string
      responses:
        "200":
          description: Feedback breakdown
  /smart-essay-marker:
    post:
      summary: Mark an essay against criteria
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [essay_text, marking_criteria]
              properties:
                essay_text:
                  type: string
                marking_criteria:
                  type: array
                  items:
                    type: string
      responses:
        "200":
          description: Marking result
  /ai-tutor:
    post:
      summary: Formative tutor feedback
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [student_draft]
              properties:
                student_draft:
                  type: string
                mode:
                  type: string
                  enum: [general, rubric]
                persona:
                  type: string
                  enum: [encouraging, direct]
      responses:
        "200":
          description: Tutor feedback points
  /reference-check:
    post:
      summary: Legacy AI detector (simplified response)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [document_text]
              properties:
                document_text:
                  type: string
      responses:
        "200":
          description: AI likelihood scores
  /ai-detector:
    post:
      summary: Hybrid AI detector (detailed response)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [document_text]
              properties:
                document_text:
                  type: string
      responses:
        "200":
          description: Hybrid detector output
  /full-reference-check:
    post:
      summary: Bibliography and citation checker
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [document_text]
              properties:
                document_text:
                  type: string
                style:
                  type: string
                  enum: [APA, Harvard, MLA, Chicago]
                enable_semantic_check:
                  type: boolean
      responses:
        "200":
          description: Citation analysis
  /rubrics:
    get:
      summary: List rubrics for the account
      responses:
        "200":
          description: Rubric list
  /students:
    get:
      summary: List students for the account
      responses:
        "200":
          description: Student list
  /classes:
    get:
      summary: List classes for the account
      responses:
        "200":
          description: Class list
  /classes/{class_id}/assignments:
    get:
      summary: List assignments for a class
      parameters:
        - name: class_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Assignment list
  /batch-style/jobs:
    post:
      summary: Create style comparison batch job
      responses:
        "202":
          description: Job queued
  /batch-style/jobs/{job_id}:
    get:
      summary: Batch style job status
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Job status
  /rubric-marking/jobs:
    post:
      summary: Create rubric marking batch job
      responses:
        "202":
          description: Job queued
  /rubric-marking/jobs/{job_id}:
    get:
      summary: Rubric marking job status
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Job status
  /automarking/jobs:
    post:
      summary: Create automarking job
      responses:
        "202":
          description: Job queued
  /automarking/jobs/{job_id}:
    get:
      summary: Automarking job status
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Job status
  /students/{student_id}/ai-history:
    get:
      summary: Student AI detection history
      parameters:
        - name: student_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: History chart data
  /students/{student_id}/progress-report:
    post:
      summary: Generate student progress report
      parameters:
        - name: student_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Progress report
  /classes/{class_id}/assignments/{assignment_id}/analyze:
    post:
      summary: Class assignment analysis
      parameters:
        - name: class_id
          in: path
          required: true
          schema:
            type: integer
        - name: assignment_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Analysis report
  /students/{student_id}/worksheet:
    post:
      summary: Generate personalized worksheet
      parameters:
        - name: student_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Worksheet payload
  /stats/users:
    get:
      summary: Total user count (admin only)
      security:
        - ApiKeyAuth: []
      responses:
        "200":
          description: User count
        "403":
          description: Non-admin key
  /jobs/estimate-cost:
    post:
      summary: Estimate async job credit cost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [job_type]
              properties:
                job_type:
                  type: string
                file_count:
                  type: integer
                student_count:
                  type: integer
      responses:
        "200":
          description: Cost estimate
  /rubrics/{rubric_id}:
    get:
      summary: Get rubric with criteria
      parameters:
        - name: rubric_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Rubric detail
  /question-templates:
    get:
      summary: List question templates
      responses:
        "200":
          description: Template list
  /style-comparison:
    post:
      summary: Sync style comparison for one student
      responses:
        "200":
          description: Comparison result
  /exam-marker/jobs:
    post:
      summary: Create exam marking job
      responses:
        "202":
          description: Job queued
  /media-marker/jobs:
    post:
      summary: Create media marking job
      responses:
        "202":
          description: Job queued
  /media-marker/jobs/{job_id}:
    get:
      summary: Media job status
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Job status
