openapi: 3.0.2
info:
  title: ChatGPT Examen Plugin API
  description: Een API voor het vinden van examenopgaves voor het Centraal Eindexamen
  version: 1.0.0
servers:
- url: https://plugin.examenchat.com
paths:
  /examenopgave_search:
    post:
      summary: Examenopgave Search
      description: 'Accepts an examenvraag (in Dutch) to find matching examenopgaves.
        Reformulate the user question into a question, as it would appear on an examen,
        using highly distinctive keywords. IMPORTANT: more than ten words! Example:
        Hoe bereken je de netto contante waarde van een investeringsproject?'
      operationId: examenopgave_search
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExamenSummaryListRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExamenSummaryListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /get_examenopgave/{examen_id}:
    post:
      summary: Get Examenopgave
      description: Returns instructions and the naam and text of an examenopgave,
        given an examen_id. The examen_id must be the exact string as returned by
        the examenopgave_search endpoint.
      operationId: get_examenopgave
      parameters:
      - required: true
        schema:
          title: Examen Id
          type: string
        name: examen_id
        in: path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExamenOpgave'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /fetch_bijlage_reference:
    post:
      summary: Examenbijlage Search
      description: Get text of a bijlage given a referentie e.g. "Informatiebron 15"
        or "Tekst 3" or "Afbeelding 6" or "Formuleblad". and the examen_id of the
        examenopgave. Always retrieve when an examenopgave vraag refers to a bijlage
        (formuleblad/bron/informatiebron/tekst/afbeelding etc)
      operationId: fetch_bijlage_reference
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExamenBijlageRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExamenBijlage'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /fetch_correctievoorschrift:
    post:
      summary: Examencorrectievoorschrift Search
      description: Get the correctievoorschrift given the examen_id of the examenopgave.
        Use if user attempts to answer an examenopgave vraag.
      operationId: fetch_correctievoorschrift
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExamenOpgaveRef'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExamenBijlage'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /save_examenvraag_punten:
    post:
      summary: Save Examenopgave Punten
      description: Save and persist the maximumscore and amount of punten (behaalde
        score) the candidate has scored on an examenvraag of an examenopgave, after
        verifying an answer to an examenvraag with the correctievoorschrift and calculating
        behaalde score.
      operationId: save_examenvraag_punten
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExamenVraagPuntenScore'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExamenVraagPuntenScoreSaveResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
components:
  schemas:
    EducationLevel:
      title: EducationLevel
      enum:
      - vwo
      - havo
      - vmbo
      description: An enumeration.
    ExamenBijlage:
      title: ExamenBijlage
      required:
      - examenbijlage_id
      - assistant_instructions
      - jaar
      - tijdvak
      - vaknaam
      - edu
      - text
      - url
      type: object
      properties:
        examenbijlage_id:
          title: Examenbijlage Id
          type: string
        assistant_instructions:
          title: Assistant Instructions
          type: string
        jaar:
          title: Jaar
          type: integer
        tijdvak:
          title: Tijdvak
          type: integer
        vaknaam:
          title: Vaknaam
          type: string
        edu:
          $ref: '#/components/schemas/EducationLevel'
        text:
          title: Text
          type: string
        url:
          title: Url
          maxLength: 2083
          minLength: 1
          type: string
          format: uri
    ExamenBijlageRequest:
      title: ExamenBijlageRequest
      required:
      - examen_id
      - referentie
      type: object
      properties:
        examen_id:
          title: Examen Id
          type: string
        referentie:
          title: Referentie
          type: string
    ExamenOpgave:
      title: ExamenOpgave
      required:
      - examen_id
      - assistant_instructions
      - naam
      - text
      - jaar
      - tijdvak
      - vaknaam
      - edu
      - text_type
      type: object
      properties:
        examen_id:
          title: Examen Id
          type: string
        assistant_instructions:
          title: Assistant Instructions
          type: string
        naam:
          title: Naam
          type: string
        text:
          title: Text
          type: string
        jaar:
          title: Jaar
          type: integer
        tijdvak:
          title: Tijdvak
          type: integer
        vaknaam:
          title: Vaknaam
          type: string
        edu:
          title: Edu
          type: string
        text_type:
          title: Text Type
          type: string
    ExamenOpgaveRef:
      title: ExamenOpgaveRef
      required:
      - examen_id
      type: object
      properties:
        examen_id:
          title: Examen Id
          type: string
    ExamenSummaryListRequest:
      title: ExamenSummaryListRequest
      required:
      - examenvraag
      type: object
      properties:
        examenvraag:
          title: Examenvraag
          type: string
        vaknaam:
          title: Vaknaam
          type: string
        keywords:
          title: Keywords
          type: array
          items:
            type: string
      description: 'The examenvraag is used to find matching examens using semantic
        search. Reformulate the

        chat user input to a question that could have appeared on an examen so that
        it can be used

        for semantic search.'
    ExamenSummaryListResponse:
      title: ExamenSummaryListResponse
      required:
      - assistant_instructions
      - examen_summaries
      type: object
      properties:
        assistant_instructions:
          title: Assistant Instructions
          type: string
        examen_summaries:
          title: Examen Summaries
          type: array
          items:
            $ref: '#/components/schemas/ExamenSummaryWithScore'
    ExamenSummaryWithScore:
      title: ExamenSummaryWithScore
      required:
      - examen_id
      - summary
      - score
      type: object
      properties:
        examen_id:
          title: Examen Id
          type: string
        summary:
          title: Summary
          type: string
        score:
          title: Score
          type: number
    ExamenVraagPuntenScore:
      title: ExamenVraagPuntenScore
      required:
      - examen_id
      - examenopgave_naam
      - vraagnummer
      - maximumscore
      - behaalde_score
      type: object
      properties:
        examen_id:
          title: Examen Id
          type: string
        examenopgave_naam:
          title: Examenopgave Naam
          type: string
        vraagnummer:
          title: Vraagnummer
          type: integer
        maximumscore:
          title: Maximumscore
          type: integer
        behaalde_score:
          title: Behaalde Score
          type: integer
    ExamenVraagPuntenScoreSaveResponse:
      title: ExamenVraagPuntenScoreSaveResponse
      required:
      - vraagnummer
      - behaalde_score
      - save_ok
      type: object
      properties:
        vraagnummer:
          title: Vraagnummer
          type: integer
        behaalde_score:
          title: Behaalde Score
          type: integer
        save_ok:
          title: Save Ok
          type: boolean
    HTTPValidationError:
      title: HTTPValidationError
      type: object
      properties:
        detail:
          title: Detail
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
    ValidationError:
      title: ValidationError
      required:
      - loc
      - msg
      - type
      type: object
      properties:
        loc:
          title: Location
          type: array
          items:
            anyOf:
            - type: string
            - type: integer
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer