Skip to content

API: Exams endpoints

/exams

GET /exams

List owned and managed exams.

[] Input:

  • string search: optional search string to filter results
  • boolean/null active: optional filter to only include active exams (if true) or inactive exams (if false)
  • integer limit: limit number of results
    • default: 16
  • integer page: page number
    • default: 1
    • not used in search mode!

[] Output:

  • list exams
    • string exam: exam identification string
    • string/null id: external unique exam identifier (if set for the exam)
    • string title: title of the exam
    • boolean active: exam is active

/exam

GET /exam

Get/check exam.

[] Input:

  • [!] string exam: exam identification string

[] Output:

  • string exam: exam identification string
  • string/null id: external unique exam identifier (if set for the exam)
  • string title: title of the exam
  • string description: description of the exam (only present if set for the exam)
  • string language: language of the exam
  • string quiz: Quiz identification string (the Quiz set the exam is attached to)
  • boolean active: exam is active
  • string status: exam status
    • INACTIVE: exam is inactive but will be activated later
    • ACTIVE: exam is active and new tests can be started
    • PAUSED: exam is active but new tests cannot be started
    • REVIEW: exam is active but already entered review period
    • EXPIRED: exam is inactive
  • boolean secure: exam can only be started with the Safe Exam Browser
  • datetime start: start date and time
  • datetime end: end date and time
  • datetime/null deadline: latest date and time the exam can be started at (if set for the exam)
  • string[url] seb_launch_url: Safe Exam Browser launch URL (only present if secure is true)
  • string[url] seb_config_url: Safe Exam Browser configuration file URL (only present if secure is true)

POST /exam

Create a new exam from an existing Quiz set.

[] Input:

  • string language: desired exam language
  • [!] string title: title of the exam
  • string{1,64} id: external unique exam identifier
  • string copy_settings: optional exam identification string to copy settings from
  • boolean keep_certificate_settings: whether to keep certificate settings from the copied exam
    • default: false
  • string type: type of the exam
    • possible values: exam / championship / homework / survey
      • exam: regular exam
      • championship: exam with championship features enabled
      • homework: homework assignment, can be paused and continued during the exam period
      • survey: survey (optionally anonymous) with no grading
    • default: exam
  • [!] string quiz: the Quiz set (specified using the Quiz identification string) the exam is attached to
  • string organization: organization identification string to assign the exam to
    • only an organization of the API application owner can be used
    • always the organization of the user for organizational members
  • [!] datetime start: exam start time
  • [!] datetime end: exam end time

[] Output:

  • string exam: exam identification string

PATCH /exam

Update the details of an existing exam.

[] Input:

  • [!] string exam: exam identification string
  • string{1,255} title: title of the exam
  • string{0,64} id: external unique exam identifier
    • send an empty value to remove the current identifier
  • string language: language of the exam
  • string description: description of the exam
    • basic HTML formatting is kept, scripts are removed
    • send an empty value to remove the current description
  • string organization: organization identification string to move the exam to
    • only an organization of the API application owner can be used
    • only the owner of the exam (or an administrator) can change the organization
    • send none (or an empty value) to remove the exam from its current organization
    • always the organization of the user for organizational members
  • datetime start: exam start time
    • can only be changed until the first result arrives
  • datetime end: exam end time
  • datetime/string deadline: latest date and time the exam can be started at
    • should be within the exam period
    • send none (or an empty value) to remove the current deadline

DELETE /exam

Remove/archive exam.

[] Input:

  • [!] string exam: exam identification string

/exam:settings

GET /exam:settings

Get the settings of an exam. Surveys are never graded and their results cannot be viewed later, so the grading and the results viewing settings are not returned for them. The columns of the results export cannot be configured for surveys either, only the format and the ordering of the exported file.

[] Input:

  • [!] string exam: exam identification string

[] Output:

  • string exam: exam identification string
  • boolean nonblocking: exam accounts are exclusively assigned to the exam and cannot be assigned to other exams during the exam period
  • boolean pausable: tests can be paused and continued later during the exam period
  • boolean questionless: the test has no questions, the examinees complete it right away by starting it (only present if not a survey or championship)
  • integer/null timelimit: time limit of the whole test in seconds
    • null: the setting of the Quiz set is used
    • 0: overridden, there is no time limit
  • integer/null roundtime: time limit of a single question in seconds (turn based Quiz sets only)
    • null: the setting of the Quiz set is used
    • 0: overridden, there is no time limit
  • boolean freeze_round: the current round of the exam is frozen, no new round can be started
  • boolean archive: the users who already have a result can be archived
  • string/null grading: grading of the exam
    • the code of the grading preset in use, custom for a manually configured grading, or none when grading is disabled
    • null: the setting of the Quiz set is used
  • integer grading_threshold: threshold of the grading in percentage (only present if a threshold is configured for the exam)
  • string view_results: when the examinees can see their results
    • after: right after the test is submitted, until the end of the exam
    • always: any time during the exam period, the examinees can log back in to see their results
    • datetime: after the test is submitted, and again from the start of the results viewing period
    • datetime_blind: only in the results viewing period, the solutions and the details of the evaluation are hidden right after the test
    • manual: only after the result is published separately, test by test
    • none: never
  • datetime/null view_results_start: start of the results viewing period (only present if view_results is datetime or datetime_blind)
  • string/null view_results_identifier: label of the custom user data field the examinees can look up their results with (only present if view_results is datetime or datetime_blind)
  • string[url] results_url: URL where examinees can look up their own results with the identifier (only present if the identifier based results page is available)
  • boolean results_page: the examinees are redirected to the results page after the test
  • boolean hide_ingame_results: the results are hidden while the test is taken
  • boolean hide_points: the points are hidden during the test and on the results page
  • boolean hide_grade: the grade is hidden on the results page
  • boolean show_in_lasthour: the results are only shown in the last hour of the exam
  • string export_format: format of the exported results file
    • csv: semicolon separated values
    • xlsx: Excel 2007+ workbook
  • string export_sort: ordering of the examinees in the exported results file
    • default: the same order they are listed in on the users page of the exam
    • name: by the name of the examinees
  • boolean export_stats: the statistics of every question are exported
  • boolean export_answers: the answers given by the examinees are exported
  • boolean export_points: the points scored on every question are exported
  • boolean export_suspicion: the suspicious test taking indicator is exported
  • boolean export_finished_only: only the examinees who finished their test are exported
  • boolean export_custom_fields: the user data fields filled in by the examinees are exported (see GET /exam:fields)
  • boolean export_skills: the skill results of the examinees are exported (only exported when the Quiz set of the exam has skills)
  • boolean export_gender: the gender of the registered examinees is exported
  • boolean export_journey: the journey status of the examinees is exported (only exported when the exam starts a journey, see GET /exam:journey)
  • boolean export_attendance: the attendance of the examinees is exported
    • read only, the attendance is configured together with its source on the interface

POST /exam:settings

Change individual settings of an exam. The columns of the export (every setting from export_stats on) cannot be configured for surveys, only the export_format and the export_sort settings are available for them. The export_attendance setting is read only, the attendance is configured together with its source on the interface.

[] Input:

  • [!] string exam: exam identification string
  • boolean nonblocking: exam accounts are exclusively assigned to the exam and cannot be assigned to other exams during the exam period
    • always true for homeworks and surveys
    • cannot be disabled when the exam already has results, or when some tests are currently paused
  • boolean pausable: allow tests to be paused and continued later during the exam period
    • only available for non-blocking exams, always true for homeworks
    • cannot be disabled when some tests are currently paused
    • automatically disabled when nonblocking is disabled
  • boolean questionless: the questions of the Quiz set are not shown, the examinees complete the test right away by starting it
    • only available if not a survey or championship
    • cannot be changed anymore when the current round already has results, until a new round is started (see POST /exam:round)
  • integer/string timelimit: time limit of the whole test in seconds, overriding the setting of the Quiz set
    • 0: there is no time limit
    • default: use the setting of the Quiz set
  • integer/string roundtime: time limit of a single question in seconds, overriding the setting of the Quiz set
    • only available for turn based (TURNS mode) Quiz sets
    • 0: there is no time limit
    • default: use the setting of the Quiz set
  • string grading: grading of the exam
    • the code of a grading preset (see GET /quiz:grading-presets), none to disable grading, or default to use the setting of the Quiz set
    • not available for surveys, they are never graded
  • number grading_threshold: threshold of the grading in percentage, between 0 and 100
    • only available for grading presets with a configurable threshold (of the go-nogo-custom type)
    • can be changed without selecting the grading preset again
  • boolean freeze_round: freeze the current round of the exam, so the Quiz set cannot be replaced and no new round can be started
    • only available for the managers of the exam
  • boolean archive: allow archiving the users who already have a result
    • only available for the managers of the exam
  • string view_results: when the examinees can see their results
    • possible values: after / always / datetime / datetime_blind / manual / none
      • after: right after the test is submitted, until the end of the exam
      • always: any time during the exam period, the examinees can log back in to see their results
      • datetime: after the test is submitted, and again from the start of the results viewing period
      • datetime_blind: only in the results viewing period, the solutions and the details of the evaluation are hidden right after the test
      • manual: only after the result is published separately, test by test
      • none: never
    • not available for surveys
    • default: after
  • datetime view_results_start: start of the results viewing period
    • only available with the datetime and datetime_blind types, where it is mandatory
    • has to be between the start and the end of the exam
    • no further tests and no new rounds can be started once the period has begun
  • string view_results_identifier: label of the unique free text custom user data field the examinees can look up their results with
    • only available with the datetime and datetime_blind types
    • the field has to be a unique free text (text, email or phone) custom field of the exam, see GET /exam:fields
    • send none (or an empty value) to disable the identifier based results page
  • boolean results_page: redirect the examinees to the results page after the test
    • can only be disabled with the datetime_blind, manual and none types
  • boolean hide_ingame_results: hide the results while the test is taken
  • boolean hide_points: hide the points during the test and on the results page
    • always enabled with the none type
  • boolean hide_grade: hide the grade on the results page
    • can only be enabled together with hide_points
    • always enabled with the none type
  • boolean show_in_lasthour: only show the results in the last hour of the exam
    • only available with the after type
  • string export_format: format of the exported results file
    • possible values: csv / xlsx
      • csv: semicolon separated values
      • xlsx: Excel 2007+ workbook
    • default: xlsx
  • string export_sort: ordering of the examinees in the exported results file
    • possible values: default / name
      • default: the same order they are listed in on the users page of the exam
      • name: by the name of the examinees
    • default: default
  • boolean export_stats: export the statistics of every question
    • default: false
  • boolean export_answers: export the answers given by the examinees
    • default: false
  • boolean export_points: export the points scored on every question
    • default: false
  • boolean export_suspicion: export the suspicious test taking indicator
    • default: false
  • boolean export_finished_only: only export the examinees who finished their test
    • default: false
  • boolean export_custom_fields: export the user data fields filled in by the examinees (see GET /exam:fields)
    • default: true
  • boolean export_skills: export the skill results of the examinees
    • only exported when the Quiz set of the exam has skills
    • default: true
  • boolean export_gender: export the gender of the registered examinees
    • needs special privileges to enable
    • default: false
  • boolean export_journey: export the journey status of the examinees

[] Output:

The updated settings of the exam are returned, the same way as with GET /exam:settings.

PUT /exam:settings

Replace the complete configuration of an exam with the configuration of another exam. Exam specific data and state (automatic account generation, rounds, notifications, login settings and previously used patterns) is never copied. Branding, and the attached learning materials (course, SCORM package and video) of the target exam are kept as well. The questionless setting is only copied if not a survey or championship, and it is kept unchanged while the current round of the target exam already has results.

[] Input:

  • [!] string exam: exam identification string (the target exam)
  • [!] string source: exam identification string to copy the settings from
    • must be different from the target exam
  • boolean keep_certificate_settings: whether to copy the certificate settings as well
    • default: false

[] Output:

  • string exam: exam identification string
  • string source: exam identification string the settings were copied from

PATCH /exam:settings

Copy only those settings from another exam that are not configured yet in the target exam.

[] Input:

  • [!] string exam: exam identification string (the target exam)
  • [!] string source: exam identification string to copy the settings from
    • must be different from the target exam
  • boolean keep_certificate_settings: whether to copy the certificate settings as well
    • default: false

[] Output:

  • string exam: exam identification string
  • string source: exam identification string the settings were copied from

/exam:fields

GET /exam:fields

Get the user data fields of an exam. These are the built-in name, email address and phone number fields, and the custom fields the examinees fill in before they start their test.

[] Input:

  • [!] string exam: exam identification string

[] Output:

  • string exam: exam identification string
  • boolean/string name: the full name of the examinee is requested
    • false: the field is not used
    • true: the field is used with its default label
    • otherwise the custom label of the field
  • boolean/string email: the email address of the examinee is requested
    • false: the field is not used
    • true: the field is used with its default label
    • otherwise the custom label of the field
  • boolean/string phone: the phone number of the examinee is requested
    • false: the field is not used
    • true: the field is used with its default label
    • otherwise the custom label of the field
  • list fields: the custom fields of the exam
    • string label: label of the field, shown to the examinee
    • string type: type of the field
    • boolean required: the field has to be filled in
    • string description: description shown under the field (if set)
    • string icon: Font Awesome icon class name of the field (if set)
    • list{string} options: the selectable options (select fields only)
    • object filtering: short labels the examinees are grouped and filtered with in the exam manager and the reports, keyed by option (select fields only, if set)
    • number from: lowest selectable value (from-to fields only)
    • number to: highest selectable value (from-to fields only)
    • number step: difference between the selectable values (from-to fields only, if set)
    • string min: earliest allowed value (date and datetime fields only, if set)
      • now: the current date (or date and time)
      • otherwise a fixed date as YYYY-MM-DD (date fields), or a date and time as YYYY-MM-DD HH:MM in UTC (datetime fields)
    • string max: latest allowed value (date and datetime fields only, if set), the same way as min
    • integer minlength: minimum length of the value (free text fields only, if set)
    • integer maxlength: maximum length of the value (free text fields only, if set)
    • string pattern: regular expression the value has to match (free text fields only, if set)
    • boolean unique: the value has to be unique within the exam (free text fields only, if set)

POST /exam:fields

Change the built-in user data fields of an exam, and replace the complete list of its custom fields. The view_results_identifier setting of the exam is cleared when the selected custom field is not a unique free text field anymore.

[] Input:

  • [!] string exam: exam identification string
  • boolean/string{1,255} name: request the full name of the examinee
    • true: use the field with its default label
    • false: do not use the field, its other settings are kept
    • any other value is used as the label of the field
  • boolean/string{1,255} email: request the email address of the examinee
    • true: use the field with its default label
    • false: do not use the field, its other settings are kept
    • any other value is used as the label of the field
  • boolean/string{1,255} phone: request the phone number of the examinee
    • true: use the field with its default label
    • false: do not use the field, its other settings are kept
    • any other value is used as the label of the field
  • list fields: the custom fields of the exam, in the order they are shown to the examinee
    • the submitted list replaces the current one, so send every custom field that should be kept
    • [!] string label: label of the field, shown to the examinee
      • the label identifies the field, so it has to be unique within the exam
      • the settings of the previous field with the same label are used as the defaults
    • string type: type of the field
      • possible values: text / email / phone / select / number / from-to / date / datetime / yes-no / yes / no / true-false / gender
        • text: free text
        • email: email address
        • phone: phone number
        • select: one of the given options
        • number: number
        • from-to: number selected from a range
        • date: calendar day, stored as YYYY-MM-DD
        • datetime: date and time, entered in the timezone of the examinee and stored as YYYY-MM-DD HH:MM in UTC
        • yes-no: yes or no
        • yes: yes only, the examinee has to accept it
        • no: no only
        • true-false: true or false
        • gender: male, female or other
      • default: text
    • boolean required: the field has to be filled in
      • default: true
    • string description: description shown under the field
    • string icon: Font Awesome icon class name of the field
      • format: fa-{style} fa-{name}, where style is solid, regular, light, thin or brands
      • example: fa-regular fa-id-card
    • list{string} options: the selectable options
      • mandatory for select fields, empty options are dropped
    • object filtering: short labels the examinees are grouped and filtered with in the exam manager and the reports, keyed by option
      • only used for select fields, and only the options of the field can be used as keys
      • the previously stored labels are kept when it is not specified
    • number from: lowest selectable value
      • mandatory for from-to fields, has to be lower than to
    • number to: highest selectable value
      • mandatory for from-to fields
    • number step: difference between the selectable values
      • only used for from-to fields, and it cannot be 0
    • string min: earliest allowed value
      • only used for date and datetime fields
      • now for the current date (or date and time) when the field is filled in, or a fixed value: YYYY-MM-DD for date fields, YYYY-MM-DD HH:MM in UTC for datetime fields
    • string max: latest allowed value
      • only used for date and datetime fields, the same way as min
      • cannot be earlier than a fixed min
    • integer minlength: minimum length of the value, between 1 and 255
      • only used for the free text (text, email and phone) fields
    • integer maxlength: maximum length of the value, between 1 and 255
      • only used for the free text (text, email and phone) fields
    • string{1,255} pattern: regular expression the value has to match
      • only used for the free text (text, email and phone) fields
      • has to be a valid expression, it is matched against the whole value
      • needs special privileges to set, the previously stored pattern is kept for everyone else
    • boolean unique: require the value to be unique within the exam
      • only used for the free text (text, email and phone) fields
      • default: false

[] Output:

The new fields of the exam are returned, the same way as with GET /exam:fields.

DELETE /exam:fields

Remove every custom field of an exam. The built-in name, email address and phone number fields are kept, use the POST method to turn those off. The values the examinees already entered are kept, but they are not shown anymore. The view_results_identifier setting of the exam is cleared as well.

[] Input:

  • [!] string exam: exam identification string

/exam:status

GET /exam:status

Get the status of an exam, showing whether new tests can be started.

[] Input:

  • [!] string exam: exam identification string

[] Output:

  • string exam: exam identification string
  • boolean active: exam is active
  • boolean status: new tests can be started
  • datetime/null modified: date and time the status was changed at
  • datetime/null scheduled: date and time starting new tests is automatically disabled at

POST /exam:status

Enable or disable starting new tests on an exam. The exam itself stays active, only the start of further tests is controlled. The status can only be changed while the exam is active and has not closed yet. New tests cannot be started in the results viewing period. Disabling new tests also cancels the scheduled automatic disabling of the exam.

[] Input:

  • [!] string exam: exam identification string
  • [!] boolean status: allow new tests to be started

[] Output:

The new status of the exam is returned, the same way as with GET /exam:status.

/exam:round

GET /exam:round

Get the current round of an exam.

[] Input:

  • [!] string exam: exam identification string

[] Output:

  • string exam: exam identification string
  • integer round: index of the current round
  • datetime/null started: date and time the current round was started at
  • boolean results: the current round already has results
  • boolean frozen: the current round is frozen, no new round can be started

POST /exam:round

Start a new round of the exam. The running tests are closed, the results of the previous round are detached from the exam accounts and the generated accounts are reset, so the exam can be taken again by another group of examinees. A new round cannot be started when the exam is locked, archived, the current round is frozen (see the freeze_round setting of POST /exam:settings), or the results viewing period of the exam has already begun (see the view_results_start setting of POST /exam:settings).

[] Input:

  • [!] string exam: exam identification string
  • boolean force: start a new round even if the current one has no results yet
    • default: false
  • boolean notify: notify the assigned users about the exam
    • default: false

[] Output:

The new round of the exam is returned, the same way as with GET /exam:round.

/exam:skills

GET /exam:skills

Get skills defined in the Quiz set used by an exam.

[] Input:

  • [!] string exam: exam identification string

[] Output:

  • string exam: exam identification string
  • list skills
    • string identifier: skill identifier
    • string title: title of the skill
    • string description: skill description (if set)

/exam:branding

GET /exam:branding

Get exam branding configuration.

[] Input:

  • [!] string exam: exam identification string

[] Output:

  • string exam: exam identification string
  • boolean enabled: whether branding is configured and enabled
  • string type: type of branding image
    • possible values: foreground / background
      • foreground: image is used as a logo
      • background: image is used as a cover
    • only present if branding is enabled
  • string color: branding color (only present if branding is enabled)

POST /exam:branding

Configure or update exam branding.

[] Input:

  • [!] string exam: exam identification string
  • string type: branding image type
    • possible values: foreground / background
      • default: foreground
  • [!] string image: branding image
    • either a base64-encoded image or a URL
    • supported formats: PNG, JPEG, WebP
  • [!] string color: branding color
    • possible values: branding / red / blue / yellow / green / purple / gray

DELETE /exam:branding

Remove branding from an exam.

[] Input:

  • [!] string exam: exam identification string

/exam:certificates

GET /exam:certificates

Get the certificate settings of an exam. Certificates are only issued for the successful results, so they need a grading that decides whether the test was successful (see the certificates flag in GET /quiz:grading-presets). Only the state of the certificates is returned when they are not enabled for the exam. When the certificates are configured by a preset, the settings of the preset are merged into the returned configuration. The certificates issued for the individual results can be looked up with GET /exam:certificates:user.

[] Input:

  • [!] string exam: exam identification string

[] Output:

  • string exam: exam identification string
  • boolean enabled: certificates are issued for the exam
    • the configuration itself is only returned when the certificates are enabled
  • boolean configured: the certificates are configured, so they can be issued
  • boolean supervisors_only: only the supervisors can issue the certificates, the examinees cannot get their own ones
  • boolean email_send: the certificates are sent to the examinees in email automatically
  • string/null preset: identification string of the certificate preset configuring the certificates (see GET /exam:certificates:presets)
    • null: the certificates are configured manually
  • string language: language of the certificates
  • string title: title of the certificates
  • string text1: text displayed under the data of the examinee
    • the multi line texts (text1, text2 and notes) are returned with basic HTML formatting and line breaks
  • string text2: text displayed under the results, above the date of the test
  • string text_date: text displayed before the date of the test
  • string notes: notes displayed at the bottom of the certificates
  • boolean show_result: the result of the test is displayed
  • boolean show_serial: the certificates get a serial number
  • boolean show_birthdate_birthplace: the birth date and the birth place of the examinee are displayed
  • boolean show_custom: custom user data is displayed
  • boolean show_expiration: the certificates expire and their validity is displayed
  • boolean show_signature: signatures are displayed
  • boolean show_custom_branding: custom branding (logo and organization name) is displayed
  • boolean hide_timezone: the timezone information is hidden
  • boolean download_automatically: the certificate is downloaded automatically when the examinee opens the results page
  • number/null grading_threshold: threshold of the certificates in percentage, overriding the threshold of the grading
    • null: the threshold of the grading is used
  • string/null timezone: timezone of the dates on the certificates
    • null: the timezone of the exam is used
  • string[] custom_fields: custom user data displayed as extra data (only present if show_custom is enabled)
    • the custom user data fields of the exam are identified by their label (see GET /exam:fields), the data fields of the user accounts by their customer_ prefixed name
  • string[] custom_user_fields: custom user data displayed together with the data of the examinee (only present if show_custom is enabled)
  • string result_format: format of the displayed result (only present if show_result is enabled)
    • possible values: points-percent-time / points-percent / points / percent
  • string serial_format: format of the serial numbers (only present if show_serial is enabled)
    • possible values: prefix-year-index / prefix-date-index / prefix-index
  • string serial_separator: separator between the parts of the serial numbers (only present if show_serial is enabled)
  • string serial_prefix: prefix of the serial numbers (only present if show_serial is enabled)
  • integer serial_index_digits: minimum length of the index in the serial numbers (only present if show_serial is enabled)
  • integer expiration: validity period of the certificates in days (only present if show_expiration is enabled)
  • boolean/integer renew: whether the certificates can be renewed (only present if show_expiration is enabled)
    • false: the certificates cannot be renewed
    • true: the certificates can be renewed any time
    • integer: the number of days the renewal is available from, relative to the expiry (0 is the day of the expiry, negative values open the renewal before it)
  • boolean manual_renewal: the renewal has to be approved by a supervisor (only present if show_expiration is enabled)
  • boolean automatic_renewal_approval: the renewal is approved automatically, but it stays revocable (only present if show_expiration is enabled)
  • string[] expiration_notification_emails: email addresses notified about the expiring certificates (only present if show_expiration is enabled)
  • boolean signature_user: a signature line is displayed for the examinee (only present if show_signature is enabled)
  • boolean signature_left: the signature of the first organizer is displayed (only present if show_signature is enabled)
  • string signature_left_line1: name of the first organizer (only present if show_signature is enabled)
  • string signature_left_line2: second line of the first signature (only present if show_signature is enabled)
  • string signature_left_line3: third line of the first signature (only present if show_signature is enabled)
  • string signature_left_line4: fourth line of the first signature (only present if show_signature is enabled)
  • boolean signature_left_image: the uploaded image of the first signature is displayed (only present if show_signature is enabled)
  • boolean signature_right: the signature of the second organizer is displayed (only present if show_signature is enabled)
  • string signature_right_line1: name of the second organizer (only present if show_signature is enabled)
  • string signature_right_line2: second line of the second signature (only present if show_signature is enabled)
  • string signature_right_line3: third line of the second signature (only present if show_signature is enabled)
  • string signature_right_line4: fourth line of the second signature (only present if show_signature is enabled)
  • boolean signature_right_image: the uploaded image of the second signature is displayed (only present if show_signature is enabled)
  • boolean signature_stamp: the uploaded stamp is displayed between the signatures (only present if show_signature is enabled)
  • string branding_line1: name of the organization (only present if show_custom_branding is enabled)
  • string branding_line2: second line of the branding (only present if show_custom_branding is enabled)
  • string branding_line3: third line of the branding (only present if show_custom_branding is enabled)
  • string branding_line4: fourth line of the branding (only present if show_custom_branding is enabled)
  • boolean branding_image: the uploaded logo is displayed (only present if show_custom_branding is enabled)
  • boolean branding_edubase: the EduBase logo is displayed (only present if show_custom_branding is enabled)

POST /exam:certificates

Change individual certificate settings of an exam. Every setting other than enabled requires the certificates to be enabled for the exam, and the items displayed on the certificates have to be switched on before their own settings can be configured (for example show_serial before the serial_ settings). The certificates configured by a preset can only be replaced completely, see PUT /exam:certificates. The settings cannot be changed while the exam is locked.

[] Input:

  • [!] string exam: exam identification string
  • boolean enabled: issue certificates for the exam
    • needs the certificate feature to be enabled for the user
    • not available for surveys, and needs a grading that decides whether the test was successful (see the certificates flag in GET /quiz:grading-presets)
    • the configuration is kept when the certificates are disabled
  • boolean supervisors_only: only allow the supervisors to issue the certificates, so the examinees cannot get their own ones
  • boolean email_send: send the certificates to the examinees in email automatically
    • needs the certificate email sending feature to be enabled on the instance
  • string language: language of the certificates
    • only the languages EduBase is translated to are available
    • default: language of the exam
  • string{1,80} title: title of the certificates
    • certificates are only issued once they have a title
  • string{0,320} text1: text displayed under the data of the examinee
    • the multi line texts (text1, text2 and notes) support basic formatting (bold, italic, underline, subscript, superscript) and line breaks
  • string{0,1280} text2: text displayed under the results, above the date of the test
  • string{0,80} text_date: text displayed before the date of the test
  • string{0,320} notes: notes displayed at the bottom of the certificates
  • boolean show_result: display the result of the test
  • boolean show_serial: give a serial number to the certificates
  • boolean show_birthdate_birthplace: display the birth date and the birth place of the examinee
  • boolean show_custom: display custom user data
  • boolean show_expiration: expire the certificates and display their validity
  • boolean show_signature: display signatures
  • boolean show_custom_branding: display custom branding (logo and organization name)
  • boolean hide_timezone: hide the timezone information
  • boolean download_automatically: download the certificate automatically when the examinee opens the results page
  • number/string grading_threshold: threshold of the certificates in percentage, between 0 and 100
    • it overrides the threshold of the grading, certificates are only issued above it
    • default: use the threshold of the grading
  • string timezone: timezone of the dates on the certificates
    • default: use the timezone of the exam
  • string[] custom_fields: custom user data to display as extra data
    • requires show_custom, at most three fields can be displayed
    • the custom user data fields of the exam are identified by their label (see GET /exam:fields), the data fields of the user accounts by their customer_ prefixed name
    • send an empty list to remove every field
  • string[] custom_user_fields: custom user data to display together with the data of the examinee
    • the same way as with custom_fields
  • string result_format: format of the displayed result
    • requires show_result
    • possible values: points-percent-time / points-percent / points / percent
      • points-percent-time: points, result in percentage and the time spent with the test
      • points-percent: points and result in percentage
      • points: points only
      • percent: result in percentage only
    • default: points-percent-time
  • string serial_format: format of the serial numbers
    • requires show_serial, and it is mandatory when the serial numbers are configured for the first time
    • possible values: prefix-year-index / prefix-date-index / prefix-index
      • prefix-year-index: prefix, the year of the test and the index
      • prefix-date-index: prefix, the date of the test and the index
      • prefix-index: prefix and index, written together
    • none of the serial_ settings can be changed anymore once a certificate is issued for the exam
  • string serial_separator: separator between the parts of the serial numbers
    • requires show_serial
    • possible values: a slash (/), a dash (-) or an empty value
    • always empty with the prefix-index format
    • default: slash
  • string{0,16} serial_prefix: prefix of the serial numbers
    • requires show_serial
    • the serial numbers are only unique within the exam, so a unique prefix is recommended
  • integer serial_index_digits: minimum length of the index in the serial numbers, between 1 and 16
    • requires show_serial
    • default: 4
  • integer expiration: validity period of the certificates in days, between 0 and 9999
    • requires show_expiration, and it is mandatory when the expiration is configured for the first time
  • boolean/integer renew: whether the certificates can be renewed
    • requires show_expiration
    • false: the certificates cannot be renewed
    • true: the certificates can be renewed any time
    • integer: the number of days the renewal is available from, relative to the expiry (0 is the day of the expiry, negative values open the renewal before it, at most the validity period earlier)
    • default: false
  • boolean manual_renewal: the renewal has to be approved by a supervisor
    • requires renew
  • boolean automatic_renewal_approval: approve the renewal automatically, but keep it revocable
    • requires manual_renewal
  • string[] expiration_notification_emails: email addresses to notify about the expiring certificates
    • requires show_expiration
    • the examinees of the exam are notified automatically about their renewable certificates, these notifications are sent to the specified addresses only
    • send an empty list to remove every address
  • boolean signature_user: display a signature line for the examinee
    • requires show_signature
  • boolean signature_left: display the signature of the first organizer
    • requires show_signature
    • the lines of the signature are kept when it is disabled
  • string{1,40} signature_left_line1: name of the first organizer
    • mandatory when the signature is displayed
  • string{0,50} signature_left_line2: second line of the first signature
  • string{0,50} signature_left_line3: third line of the first signature
  • string{0,50} signature_left_line4: fourth line of the first signature
  • boolean/string signature_left_image: image of the first signature
    • the identifier of an image uploaded to the filebin replaces the image (supported formats: JPEG, WebP, PNG)
    • the white background of the signatures and the stamp is removed automatically, but transparent PNG images are recommended
    • true: display the image that is already uploaded
    • false: keep the uploaded image, but do not display it
  • boolean signature_right: display the signature of the second organizer
    • the same way as with signature_left
  • string{1,40} signature_right_line1: name of the second organizer
    • mandatory when the signature is displayed
  • string{0,50} signature_right_line2: second line of the second signature
  • string{0,50} signature_right_line3: third line of the second signature
  • string{0,50} signature_right_line4: fourth line of the second signature
  • boolean/string signature_right_image: image of the second signature
    • the same way as with signature_left_image
  • boolean/string signature_stamp: stamp displayed between the signatures
    • the same way as with signature_left_image
  • string{1,80} branding_line1: name of the organization
    • requires show_custom_branding, and it is mandatory when the branding is displayed
  • string{0,80} branding_line2: second line of the branding
  • string{0,80} branding_line3: third line of the branding
  • string{0,80} branding_line4: fourth line of the branding
  • boolean/string branding_image: logo of the branding
    • the same way as with signature_left_image
  • boolean branding_edubase: display the EduBase logo
    • it can only be removed with the matching feature enabled

[] Output:

The updated certificate settings of the exam are returned, the same way as with GET /exam:certificates.

PUT /exam:certificates

Replace the complete certificate configuration of an exam with a preset or with the configuration of another exam. The certificates have to be enabled for the exam, and its settings cannot be changed while it is locked.

[] Input:

  • [!] string exam: exam identification string (the target exam)
  • string preset: certificate preset identification string (see GET /exam:certificates:presets)
    • the settings of the preset are applied to the exam, and they are kept up to date with the preset
  • string source: exam identification string to copy the certificate configuration from
    • must be different from the target exam, and its certificates have to be configured manually (not by a preset)
    • the images (signatures, stamp and logo) are copied as well

[] Output:

The updated certificate settings of the exam are returned, the same way as with GET /exam:certificates.

DELETE /exam:certificates

Stop issuing certificates for an exam. The configuration itself is kept, so the certificates can be enabled again later with POST /exam:certificates. The already issued certificates are not revoked. The settings cannot be changed while the exam is locked.

[] Input:

  • [!] string exam: exam identification string

[] Output:

The updated certificate settings of the exam are returned, the same way as with GET /exam:certificates.

/exam:certificates:presets

GET /exam:certificates:presets

List the certificate presets that can be used on exams. The public presets, the owned presets and the presets of the organizations of the user are returned.

[] Input:

  • string exam: exam identification string
    • only the presets that can be used on this exam are listed
    • the language of the exam is used for the ordering of the presets
  • string language: optional language to filter the results with

[] Output:

  • string exam: exam identification string (only present if an exam is specified)
  • list presets
    • string preset: certificate preset identification string
    • string title: title of the certificate preset
    • string language: language of the certificate preset
    • boolean public: the preset is a public preset available for everyone
    • boolean own: the preset is a custom preset owned by the user
    • string/null organization: organization identification string of the preset
      • null: the preset is not bound to an organization
    • boolean current: the certificates of the exam are configured by this preset

/exam:users

GET /exam:users

List all users on an exam.

[] Input:

  • [!] string exam: exam identification string

[] Output:

  • list users
    • string user: user identification string
    • string name: name of the examinee

POST /exam:users

Assign user(s) to an exam.

[] Input:

  • [!] string exam: exam identification string
  • [!] string users: comma-separated list of user identification strings

DELETE /exam:users

Remove user(s) from an exam.

[] Input:

  • [!] string exam: exam identification string
  • [!] string users: comma-separated list of user identification strings

/exam:users:generate

POST /exam:users:generate

Generate exam accounts from patterns and assign them to an exam.

Patterns

The following placeholders can be used in the patterns:

  • {index}: the index of the generated account
  • {random:N}: a random alphanumeric string of N characters (unambiguous characters only in passwords)
  • {number:N}: a random numeric string of N characters
  • {name} and {Name}: the name of the account (only when names is specified), as given and capitalized
  • {username}: the generated username (in the name pattern only)

Patterns are stored with the exam and reused as defaults for the next call.

[] Input:

  • [!] string exam: exam identification string
  • string{1,64} username: username pattern
    • defaults to the pattern used previously for this exam
    • mandatory if the exam has no previously used pattern
  • string{1,64} password: password pattern
    • defaults to the pattern used previously for this exam
    • mandatory if the exam has no previously used pattern
  • string{1,128} name: full name pattern
    • defaults to the pattern used previously for this exam
    • mandatory if the exam has no previously used pattern
  • list{string}/string names: list of names to generate the accounts for
    • either a list, or a comma or newline separated string
    • the number of accounts generated is the number of names specified, count is ignored
  • list{string}/string emails: list of email addresses for the generated accounts
    • either a list, or a comma or newline separated string
    • only used together with names, the number of items must match the number of names
    • invalid addresses are replaced with a generated one
  • integer count: number of accounts to generate
    • between 1 and 500
    • ignored when names is specified
    • default: 1
  • integer start: index to start the generation at
    • default: the index after the previously generated accounts (1 for the first call)

[] Output:

  • string exam: exam identification string
  • list users
    • string user: user identification string
    • string username: username of the generated account
    • string name: full name of the generated account
    • string/null password: password of the generated account (if available)
  • list{string} failed: usernames of the accounts that could not be created (only present if there are any)
  • list{string} duplicate: usernames that were skipped because the same account was being generated by a parallel request at the same time (only present if there are any)

/exam:autologin

GET /exam:autologin

Get the automatic login configuration of an exam.

[] Input:

  • [!] string exam: exam identification string

[] Output:

  • string exam: exam identification string
  • boolean autologin: automatic login is enabled
  • string pin: PIN code of the exam (only present if autologin is true and a PIN code is set)
  • string[url] url: login URL of the exam
    • only present if autologin is true
    • the Safe Exam Browser launch URL will be used if the exam is secure, otherwise the shortlink will be used if it is set, and the standard login URL will be used if neither of the two is available
  • string[url] results_url: URL where examinees can look up their own results (only present if autologin is true and results can be viewed with an identifier)
  • boolean autoadd: new exam accounts are generated automatically on demand (only present if autologin is true)
  • boolean autojoin: already registered users can join the exam automatically (only present if autologin is true)
  • boolean autojoin_limited: automatic joining is limited to the assigned users (only present if autojoin is true)

POST /exam:autologin

Enable or reconfigure automatic login for an exam.

[] Input:

  • [!] string exam: exam identification string
  • string se: shortlink for the login URL
    • at least 3 characters long
    • a + sign will be prefixed automatically, and the shortlink is case-insensitive
    • send an empty value to remove the current shortlink
    • needs the shortlink feature to be enabled, and cannot be used with secure (Safe Exam Browser) exams
  • boolean autoadd: generate new exam accounts automatically on demand
    • needs special privileges to set!
  • boolean autojoin: allow already registered users to join the exam automatically
    • needs special privileges to set!
  • boolean autojoin_limited: limit automatic joining to the users assigned to the exam
    • only used when autojoin is enabled
    • needs special privileges to set!
    • default: false

[] Output:

The automatic login configuration of the exam is returned, the same way as with GET /exam:autologin.

DELETE /exam:autologin

Disable automatic login for an exam. The PIN code and the shortlink of the exam are removed as well.

[] Input:

  • [!] string exam: exam identification string

/exam:journey

GET /exam:journey

Get the status of the journey started by an exam: the number of users at the steps, their statuses, and the outcomes of the finished journeys. Only the organizational members visible for the current user are counted.

[] Input:

  • [!] string exam: exam identification string (the starting exam)

[] Output:

  • string exam: exam identification string
  • string journey: title of the journey (the title of the exam, unless a custom title is set)
  • boolean active: the journey is enabled, users enter it when they start the exam
  • datetime/null published: date and time the journey was last published at
    • null: the journey is not published yet
  • integer users: number of users on the journey
  • hash status: number of users by their status
    • integer active: on a step, working on its content
    • integer waiting: waiting before they can continue
    • integer error: stuck on a step that cannot be completed (e.g. its content was removed)
    • integer completed: finished the journey
    • integer stopped: their journey was stopped by an educator
  • list outcomes: outcomes of the finished (completed or stopped) journeys
    • string/null outcome: the outcome
    • integer users: number of users finishing with the outcome
  • list steps: steps of the journey (every node except the decisions and actions), in the order of their markers
    • string step: key of the step (node)
    • string marker: marker letter of the step (A, B, ..., Z, AA, ...), ordered by their position on the canvas
    • string type: type of the step
      • possible values: start / exam / class / quiz / wait / end
    • string title: title of the step (the title of its content, unless a custom label is set)
    • hash/null content: content of the step (the starting exam for the start step, null if not selected or not available anymore)
      • string type: type of the content
        • possible values: exam / class / quiz
      • string exam / class / quiz: identification string of the content (keyed by its type)
      • string/null id: external unique identifier of the content (if set)
      • string title: title of the content
    • string outcome: outcome given by the step (only present for end steps)
    • integer users: number of users currently at the step
    • hash status: number of users currently at the step by their status (the same way as above)
    • integer passed_users: number of users who already passed the step (not present for end steps)
    • integer passed_visits: number of times the step was passed, including the repeated visits (not present for end steps)
    • float/null result_average: average result of the completed step in percentage (not present for end steps)
    • integer/null time_spent_average: average time spent at the step in seconds (not present for end steps)

/exam:journey:user

GET /exam:journey:user

Get the journey of a user started by an exam: the current step, the history of the visited steps and the manual changes made by the educators.

[] Input:

  • [!] string exam: exam identification string (the starting exam)
  • [!] string user: user identification string

[] Output:

  • string exam: exam identification string
  • string journey: title of the journey
  • string user: user identification string
  • string/null status: status of the journey of the user
    • possible values: active / waiting / error / completed / stopped
    • null: the user has not entered the journey yet (users enter the journey by starting the exam), no other fields are returned
  • string/null outcome: outcome of the journey (only set if status is completed or stopped)
  • string error: code of the error (only present if status is error)
    • possible values: content-invalid / content-archived / content-locked / content-closed / class-not-progressive / class-membership-missing / class-membership-expired / attempts-exhausted / enroll-failed / error
  • integer run: index of the current run of the journey (increased when the journey is restarted)
  • hash/null step: the current step of the user (null if the journey is finished)
    • the same fields as the items of steps of GET /exam:journey, without the user counts
    • datetime time_start: date and time the step was entered at
  • datetime wait_until: date and time the waiting ends at (only present if status is waiting and the end is known)
  • datetime time_start: date and time the user entered the journey at
  • datetime/null time_end: date and time the user finished the journey at
  • integer steps_completed: number of the different exam, class and Quiz set steps completed in the current run (the start step included)
  • integer steps_total: number of the exam, class and Quiz set steps of the journey (the start step included)
  • integer/null steps_remaining: estimated number of steps still to be completed on the shortest way to the end
    • a lower bound, the decisions may lead to a longer path
    • null: the journey is not running, or no end can be reached from the current step
  • hash flags: flags set for the user by the flag actions of the journey, keyed by their name (only present if there are any)
  • list history: the visited steps of every run, in the order they were entered
    • integer run: index of the run
    • integer visit: index of the visit of the step within the run
    • string step, marker, type, title, content, outcome: the step, the same way as with GET /exam:journey
    • string status: status of the visit
      • possible values: active / waiting / completed / moved / stopped / error
    • datetime time_start: date and time the step was entered at
    • datetime/null time_end: date and time the step was left at
    • integer/null time_spent: time spent taking the test of the step in minutes
    • float result: result in percentage (only present if available)
    • boolean successful: the test was successful (only present if available)
    • string grade: grade of the test (only present if available)
    • string play: Quiz play identification string of the test completing the step (only present if available)
    • hash skills: skill results of the test, keyed by the skill identifier (only present if available)
    • list decisions: decisions and actions passed after the step, with the outputs taken (only present if there are any)
      • string decision: key of the decision or action node
      • string/null type: type of the node
        • possible values: condition / split / notify / flag / mark
      • string/null title: title of the node
      • string/null output: output taken (the key of a branch, else or next)
      • string/null label: label of the branch taken (if set)
  • list events: manual changes of the journey of the user
    • integer run: index of the run
    • string type: type of the change
      • possible values: move / stop / resume / restart
    • string source: source of the change
      • operator: made by an educator
      • publish: made by publishing a new version of the journey (the user was on a removed step)
    • hash from: the state before the change
      • string/null step: key of the step
      • string/null status: status of the journey
    • hash to: the state after the change (the same way as from)
    • string/null operator: user identification string of the educator making the change
    • datetime time: date and time of the change

/exam:journey:graph

Portable JSON Format

The journeys are exported and imported in a portable JSON format, where the contents are referenced by their identification strings. The format is described by a JSON Schema, and it is the same format the journey editor exports and imports files with.

  • integer schema: version of the format, currently 1
  • hash settings: settings of the journey, every key is optional
    • string/null title: custom title of the journey (at most 255 characters)
    • string/null description: description of the journey (at most 1024 characters)
    • integer max_visits: maximum visits of a node by a user, between 1 and 50, loops stop with the loop-limit outcome (default: 5)
    • boolean restartable: finished journeys can be started again by taking the starting exam again
    • boolean notify_user: notify the users when they finish the journey
    • list{string} educators: user identification strings of the educators notified by the journey, e.g. about its errors and by the notify nodes (at most 10, only the owner and the managers of the starting exam, the owner is notified if none are set)
  • list nodes: nodes of the journey (at most 200)
    • string node: stable key of the node, unique within the journey (1-32 letters, digits, - or _)
    • string type: type of the node
      • steps (the users stay until they complete them): start (exactly one, the starting exam itself), exam, class, quiz
      • decisions and actions (passed instantly): condition, split, notify, flag, mark
      • wait: waits before continuing
      • end: finishes the journey
    • string/null label: custom title of the node (at most 64 characters)
    • hash position: position of the node on the canvas (x and y), nodes without a position are laid out automatically
    • hash config: configuration of the node, depending on its type
      • start: complete_on (when the step is completed: finish when the exam is finished, success when it is finished successfully, final when its result is final)
      • exam: exam (exam identification string), complete_on (see above), retake (revisiting the step grants a retake), reuse (results achieved before entering the step complete it)
      • class: class (class identification string), reuse (an earlier completion of the class completes the step on every visit)
      • quiz: quiz (Quiz set identification string), min_result (minimum result of a play completing the step in percentage), min_plays (number of plays needed, between 1 and 100)
      • condition: branches (at most 16, evaluated in order, the first matching one is taken, else otherwise), each with a key, a label, a match mode (all or any of the rules) and at most 16 rules; else_label (label of the else output)
      • split: branches (at least 2, at most 16) with a key, a label and a relative weight (0-1000) to split the users randomly
      • wait: mode and its settings
        • duration: for minutes (between 1 and 525600)
        • date: until the date, given either as YYYY-MM-DD HH:MM in the timezone of the node (the same moment for every user), or as YYYY-MM-DD (the start of that day in the timezone of each user)
        • weekday: until the next weekday from 1 (Monday) to 7 (Sunday), at the optional time given as HH:MM in the timezone of the node, or at the start of that day in the timezone of each user without a time
        • timezone: IANA name like Europe/Budapest, used with a date and time or a weekday time (default: UTC)
      • notify: target (user or educators), message (at most 500 characters)
      • flag: name of the flag to set and its value (at most 64 characters)
      • mark: mode (mark or unmark the user on the users page of the starting exam)
      • end: outcome of the finished journey (completed, failed, or any custom text of at most 64 characters, default: completed)
    • hash next: keys of the nodes following this node, keyed by the outputs of this node
      • steps have a single done output, waits and actions a single next output, conditions have an output for each branch key and an else output, splits an output for each branch key, end nodes have no outputs
      • an output left out or set to null is unconnected, users taking it finish the journey with the completed outcome
    • string marker, title, hash content: informative only, ignored by the import

The rules of the conditions have the following fields:

  • string field: the compared value
    • the completed step: step.result, step.successful, step.grade, step.attempts, step.time_spent, step.visits, step.skill
    • an earlier node of the journey: node.result, node.successful, node.grade, node.time_spent, node.completed, node.visits, node.skill
    • the user: exam.custom, user.gender, user.customer_field, user.department, user.team, user.generated
    • the journey and the current date: journey.flag, journey.days, journey.steps, date.weekday, date.hour, date.date, date.datetime
    • results are compared as percentages (0-100)
  • string param: parameter of the field (at most 64 characters)
    • needed by step.skill (skill identifier), the node.* fields (node key, or node key and skill identifier separated by a colon for node.skill), exam.custom (exam identification string and field label or hash separated by a colon), user.customer_field (name of the field) and journey.flag (name of the flag)
  • string operator: the comparison
    • possible values: eq / neq / gt / gte / lt / lte / between / in / not_in / contains / empty / not_empty / is_true / is_false
    • empty, not_empty, is_true and is_false need no value, between needs a [minimum, maximum] list (inclusive), in and not_in need a list (at most 64 items)
  • mixed value: value to compare with
    • dates are YYYY-MM-DD calendar days and are never converted (date.date is the current day of the user)
    • date and time values are YYYY-MM-DD HH:MM, in UTC for exam.custom (datetime custom fields are stored in UTC, and compared by the day of the user when the rule has dates), and in the timezone of the rule for date.datetime
    • a between range has to use the same kind of value for both limits (two dates, or two date and time values)
    • departments are given by their titles, teams by their identification strings
  • string aggregate: which completion of an earlier node is compared (node.* fields, except node.completed and node.visits)
    • possible values: last / first / best / worst / average
    • default: last
  • string measure: whether the collected points or the percentage of the maximum is compared (skill fields)
    • possible values: points / percent
    • default: points
  • string time: the rule only matches on the listed days from this time on, given as HH:MM (date.weekday only, optional)
  • string timezone: timezone the rule is evaluated in (IANA name like Europe/Budapest)
    • used by date.hour, date.datetime, and date.weekday with a time, the other date fields use the timezone of the user
    • default: UTC

GET /exam:journey:graph

Export the draft or the published version of the journey started by an exam in the portable format.

[] Input:

  • [!] string exam: exam identification string (the starting exam)
  • string graph: version of the journey to export
    • possible values: draft / published
      • draft: the version under editing, always available
      • published: the version used by the users, only available once the journey is published
    • default: draft

[] Output:

  • string[url] $schema: URL of the JSON Schema of the format
  • integer schema: version of the format
  • string exam: exam identification string
  • string journey: title of the journey
  • boolean active: the journey is enabled
  • integer version: number of the published version
  • datetime/null published: date and time the journey was last published at
  • string graph: the exported version (draft or published)
  • boolean unpublished_changes: the draft differs from the published version
  • hash settings: settings of the journey (see above)
  • list nodes: nodes of the journey, ordered by their position (see above)
    • every output of the nodes is listed in next, the unconnected ones with null
  • list issues: problems of the draft (only present if graph is draft)
    • string level: severity of the problem
      • error: blocks publishing
      • warning: informative only
    • string code: code of the problem
    • string/null node: key of the node with the problem
    • string/null output: output of the node with the problem
    • string message: readable description of the problem
  • boolean publishable: the draft has no errors, so it can be published (only present if graph is draft)

PUT /exam:journey:graph

Replace the draft of the journey started by an exam with a journey in the portable format, and optionally update its settings. The import is strict: every problem is reported at once, and nothing is saved if there is any. If the exam does not start a journey yet, the journey is created and enabled (the simple chaining of the exam to a next exam is removed). The draft is not used by the users until it is published, see POST /exam:journey:publish. Needs the exam journeys feature to be enabled and modification permission for the exam. Archived exams and championships cannot start a journey.

[] Input:

  • [!] string exam: exam identification string (the starting exam)
  • [!] list nodes: nodes of the journey in the portable format (see above)
    • can also be given as a JSON encoded string
    • the contents of the steps have to be controlled by the current user, or already be used by the journey
    • departments are looked up in the organization of the starting exam, teams among the teams of the current user
  • hash settings: settings of the journey (see above)
    • can also be given as a JSON encoded string
    • the given keys are merged over the current settings
  • integer schema: version of the format
    • default: 1

[] Output:

The saved draft is returned, the same way as with GET /exam:journey:graph, together with:

  • list{string} ignored: unknown fields that were ignored by the import (only present if there are any)

/exam:journey:publish

POST /exam:journey:publish

Publish the draft of the journey started by an exam, so the users continue on the new version. The draft can only be published if it has no errors (see the issues of GET /exam:journey:graph). If some users are on nodes removed from the draft, a new node has to be specified for each of them with remap, otherwise the journey is not published and the affected nodes are listed in the error message. Needs the exam journeys feature to be enabled and modification permission for the exam.

[] Input:

  • [!] string exam: exam identification string (the starting exam)
  • hash remap: the users on the removed nodes are moved to these nodes
    • keyed by the key of the removed node, the value is the key of an existing node of the draft, or an empty string to stop the journeys of the users
    • can also be given as a JSON encoded string

[] Output:

  • string exam: exam identification string
  • string journey: title of the journey
  • boolean active: the journey is enabled
  • integer version: number of the published version
  • datetime published: date and time the journey was published at
  • boolean unchanged: the draft equals the published version, so nothing was published (only present if true, remapped and issues are not returned then)
  • hash remapped: the removed nodes the users were moved from, with the keys of their new nodes (null if their journeys were stopped, only present if any users were moved)
  • list issues: remaining warnings of the published version, the same way as with GET /exam:journey:graph
  • string warning: the journey is published but disabled, the users do not enter it until it is enabled in the settings of the exam (only present if the journey is disabled)

/exam:summary

POST /exam:summary

Submit a new exam summary.

[] Input:

  • [!] string exam: exam identification string
  • string language: summary language
  • string type: type of summary
    • possible values: ai
    • default: ai
  • [!] string summary: summary text
    • basic HTML formatting allowed, but avoid complex designs
    • keep the summary short and concise
    • try to avoid including personal information (such as usernames, names and contact addresses)
  • string llm: name of the Large Language Model used to generate the summary (in case of AI summaries)
    • preferred values: openai / claude / gemini
  • string model: exact LLM model name used to generate the summary (in case of AI summaries)
    • must specify llm field as well