API Reference

The REST API CodeJudge is publicly available for you to use. The API is located at https://app.codejudge.net/api. If you use it for any critical systems, please send us an e-mail, so we can notify you in case of changes.

Authentication

The API is using JWT token-based authentication. The JWT token should be sent in the authorization Bearer header of each request to the API.

Obtaining a JWT (JSON Web Token)

To obtain a JWT, one must first generate an API token through the web client. The differences between JWT and API tokens are:

JWT: The JWT authenticates the user to all the API endpoints. The JWT is short lived for security reasons. After it expires, a new one has to be generated using the API token.
API token: The API token is a long-lived token, which can only be used to obtain a valid JWT. The API tokens can be invalidated in the web client.

We are using API tokens to obtain JWT's to avoid the user having to use password authentication when accessing the API.

An API token can be generated through the web client by navigating to the "API tokens" page from the user menu (opened by clicking on the user name in the upper right corner).

Using the newly generated API token a JWT can now be obtained through the /auth/token endpoint (which is the only endpoint not requiring an Authorization header with a valid JWT).

Here is how it could be done in python:

import requests
import json

api_url = "https://app.codejudge.net/api/"
api_token = "token" # insert generated API token from CodeJudge

model = { "grantType": "refresh_token", "refreshToken": api_token }
jwtReq = requests.post(api_url + "auth/token", data=json.dumps(model))
jwtReq.raise_for_status()
jwt = jwtReq.json()["accessToken"]

We can now authenticate to the API, e.g. to get the submission with id=100:

# ... continued

submission_id = 100
headers = {"Authorization": "Bearer " + jwt}
req = requests.get(api_url + "submissions/" + str(submission_id), headers=headers)
req.raise_for_status()
submission = req.json()

print(submission)

Actions

Auth

Http Method

Path

Description

Post

/api/auth/token

Generate access token for API

Post

/api/auth/api-token

Delete

/api/auth/api-token/id

Get

/api/auth/api-tokens

Courses

Http Method

Path

Description

Get

/api/courses

Get

/api/courses/id

Put

/api/courses/id

Get

/api/courses/by-url/courseUrl

Get

/api/courses/id/user-statistics

Get

/api/courses/id/statistics

Get

/api/courses/id/languages

Post

/api/courses/id/synchronize-cas

Post

/api/courses/id/report

Post

/api/courses/id/sync

Get

/api/courses/id/exported-zip

ExerciseCollections

Http Method

Path

Description

Get

/api/exercise-collections

Post

/api/exercise-collections

Get

/api/exercise-collections/id

Put

/api/exercise-collections/id

Delete

/api/exercise-collections/id

Post

/api/exercise-collections/id/move

Post

/api/exercise-collections/id/sync

Get

/api/exercise-collections/id/exported-zip

Get

/api/exercise-collections/submissions

Get

/api/exercise-collections/id/submissions

Get

/api/exercise-collections/id/submissions/userId

Post

/api/exercise-collections/id/open/userId

Get

/api/exercise-collections/id/invitations/userId

Post

/api/exercise-collections/id/invite-user/userId

Post

/api/exercise-collections/id/accept-invitation/ownerUserId

Post

/api/exercise-collections/id/reject-invitation/ownerUserId

Post

/api/exercise-collections/id/remove-group-member/userId

Post

/api/exercise-collections/id/leave-group

Put

/api/exercise-collections/id/groups/ownerUserId/comment

Put

/api/exercise-collections/id/groups/ownerUserId/feedback

Post

/api/exercise-collections/id/activate-passive-submissions

Get

/api/exercise-collections/id/download-submissions

Exercises

Http Method

Path

Description

Get

/api/exercises

Post

/api/exercises

Get

/api/exercises/results

Get

/api/exercises/id

Put

/api/exercises/id

Delete

/api/exercises/id

Get

/api/exercises/id/solutions

Get

/api/exercises/id/attachment/filename

Get

/api/exercises/id/sample-test

Get

/api/exercises/id/data-file

Get

/api/exercises/id/data-files

Get

/api/exercises/id/stats

Get

/api/exercises/id/exported-zip

Post

/api/exercises/id/move

Post

/api/exercises/id/sync

Get

/api/exercises/id/plagiarism-groups

Post

/api/exercises/id/plagiarism-report

FaqEntries

Http Method

Path

Description

Get

/api/faq-entries

Post

/api/faq-entries

Get

/api/faq-entries/id

Put

/api/faq-entries/id

Delete

/api/faq-entries/id

Pages

Http Method

Path

Description

Get

/api/pages

Post

/api/pages

Get

/api/pages/id

Put

/api/pages/id

Delete

/api/pages/id

Submissions

Http Method

Path

Description

Get

/api/submissions

Post

/api/submissions

Get

/api/submissions/id

Get

/api/submissions/id/file-links

Get

/api/submissions/id/file/fileId

Get

/api/submissions/id/download-files

Post

/api/submissions/id/mark-not-late

Post

/api/submissions/id/regrade/testGroupId

Get

/api/submissions/id/plagiarism-group

Get

/api/submissions/id/plagiarism-comparison/otherId

Templates

Http Method

Path

Description

Get

/api/templates

Post

/api/templates

Get

/api/templates/id

Put

/api/templates/id

Delete

/api/templates/id

Post

/api/templates/id/copy

Get

/api/templates/id/data-file

Get

/api/templates/id/data-files

Get

/api/templates/id/exported-zip

TestGroupRuns

Http Method

Path

Description

Get

/api/test-group-runs

Get

/api/test-group-runs/id/data

Get

/api/test-group-runs/id/debug-data

Get

/api/test-group-runs/id/all-data

TestGroups

Http Method

Path

Description

Get

/api/test-groups

Post

/api/test-groups

Get

/api/test-groups/id

Put

/api/test-groups/id

Delete

/api/test-groups/id

Get

/api/test-groups/id/generation-data-file

Get

/api/test-groups/id/generation-data

Post

/api/test-groups/id/generate

Get

/api/test-groups/id/data-file

Get

/api/test-groups/id/data-files

Get

/api/test-groups/id/generated-files

TestRuns

Http Method

Path

Description

Get

/api/test-runs/id

Tests

Http Method

Path

Description

Get

/api/tests

Get

/api/tests/testGroupId/name

Users

Http Method

Path

Description

Get

/api/users/auth-user

Get

/api/users/id

Put

/api/users/id

Get

/api/users/for-course/courseId

Get

/api/users/id/for-course/courseId

Post

/api/users

Models

ApiTokenModel

Name

Type

Description

token

Type: string

expires

Type: date

lastUsed

Type: date

CollectionStatistics

Name

Type

Description

exerciseCollectionId

Type: integer

exerciseCollectionName

Type: string

exercises

Type: array of ExerciseStatistics

CourseModel

Name

Type

Description

Type: integer

urlName

Type: string

shortName

Type: string

name

Type: string

useCasLogin

Type: boolean

[Admin Only]

casCourseNames

Type: string

[Admin Only]

casLastSynchronized

Type: date

[Admin Only]

expires

Type: date

culture

Type: string

codeLanguages

Type: array of Language

showExercises

Type: boolean

showAssignments

Type: boolean

showSolvedBy

Type: boolean

userCourseRole

Type: UserCourseRole

CourseStatisticsModel

Name

Type

Description

submissionsPrDay

Type: array of SubmissionsDay

collections

Type: array of CollectionStatistics

CourseUserModel

Name

Type

Description

userId

Type: integer

email

Type: string

[Admin Only]

name

Type: string

studentId

Type: string

courseId

Type: integer

tag

Type: string

[Admin Only]

role

Type: UserCourseRole

[Admin Only]

CourseUserStatisticsModel

Name

Type

Description

totalSubmissions

Type: integer

DataFileModel

Name

Type

Description

name

Type: string

content

Type: string

isTruncated

Type: boolean

ExerciseCollectionModel

Name

Type

Description

Type: integer

courseId

Type: integer

type

Type: ExerciseCollectionType

name

Type: string

created

Type: date

[Admin Only]

visibleFrom

Type: date

[Admin Only]

description

Type: string

groupsAllowed

Type: boolean

commentsAllowed

Type: boolean

visibleToAuthors

Type: boolean

[Admin Only]

due

Type: date

timeLimit

Type: integer

postSubmissionsAllowed

Type: boolean

ExerciseCollectionSubmissionModel

Name

Type

Description

exerciseCollectionId

Type: integer

ownerUserId

Type: integer

members

Type: array of GroupMemberModel

exerciseResults

Type: array of ExerciseResultModel

comment

Type: string

feedback

Type: string

startTime

Type: date

ExerciseModel

Name

Type

Description

Type: integer

exerciseCollectionId

Type: integer

name

Type: string

description

Type: string

languages

Type: array of Language

customSuggestedSolution

Type: string

[Admin Only]

suggestedSolutionVisibility

Type: SolutionVisibility

useCustomSuggestedSolution

Type: boolean

[Admin Only]

hasSuggestedSolution

Type: boolean

createdDateTime

Type: date

[Admin Only]

priority

Type: integer

templateId

Type: integer

[Admin Only]

attachments

Type: array of FileModel

files

Type: array of FileModel

[Admin Only]

ExerciseResultModel

Name

Type

Description

exercise

Type: ExerciseModel

bestSubmission

Type: SubmissionModel

submissionCount

Type: integer

ExerciseSolutionModel

Name

Type

Description

language

Type: Language

files

Type: array of TextFileModel

ExerciseStatistics

Name

Type

Description

exerciseId

Type: integer

exerciseName

Type: string

submissionCount

Type: integer

averageSubmissionCount

Type: number

solvedCount

Type: integer

attemptedCount

Type: integer

ExerciseStatsModel

Name

Type

Description

solvedByUsers

Type: array of CourseUserModel

attemptedByUsers

Type: array of CourseUserModel

FaqEntryModel

Name

Type

Description

Type: integer

courseId

Type: integer

title

Type: string

description

Type: string

priority

Type: integer

created

Type: date

[Admin Only]

lastModified

Type: date

[Admin Only]

FileModel

Name

Type

Description

name

Type: string

contentKey

Type: string

uploadContent

Type: string

GenerationDataModel

Name

Type

Description

testGroupId

Type: integer

files

Type: array of TextFileModel

GroupMemberModel

Name

Type

Description

studentId

Type: string

userId

Type: integer

name

Type: string

accepted

Type: boolean

InvitationModel

Name

Type

Description

groupOwnerId

Type: integer

groupOwnerName

Type: string

LanguageModel

Name

Type

Description

language

Type: Language

name

Type: string

mainExtension

Type: string

version

Type: string

PageModel

Name

Type

Description

Type: integer

courseId

Type: integer

title

Type: string

menuName

Type: string

urlName

Type: string

content

Type: string

requiresLogin

Type: boolean

[Admin Only]

requiresAdmin

Type: boolean

[Admin Only]

PlagiarismCompareGroupModel

Name

Type

Description

group

Type: ExerciseCollectionSubmissionModel

submission

Type: SubmissionModel

score

Type: number

PlagiarismComparisonModel

Name

Type

Description

submissionText

Type: string

otherSubmissionText

Type: string

matches

Type: array of PlagiarismMatchModel

PlagiarismGroupModel

Name

Type

Description

group

Type: ExerciseCollectionSubmissionModel

submission

Type: SubmissionModel

highestScore

Type: number

compareGroups

Type: array of PlagiarismCompareGroupModel

PlagiarismMatchModel

Name

Type

Description

from

Type: integer

matchesFrom

Type: integer

matchesTo

Type: integer

ReportPostModel

Name

Type

Description

ids

Type: array of integer

exerciseFields

Type: array of ExerciseField

testGroupFields

Type: array of TestGroupField

testFields

Type: array of TestField

submissionType

Type: SubmissionType

includeInstructors

Type: boolean

includeLateSubmissions

Type: boolean

RequestTokenModel

Name

Type

Description

grantType

Type: string

username

Type: string

password

Type: string

refreshToken

Type: string

ResponseTokenModel

Name

Type

Description

accessToken

Type: string

refreshToken

Type: string

ResultViewMarking

Name

Type

Description

length

Type: integer

column

Type: integer

line

Type: integer

ResultViewModel

Name

Type

Description

type

Type: ResultViewType

title

Type: string

SaveCommentModel

Name

Type

Description

comment

Type: string

SaveFeedbackModel

Name

Type

Description

feedback

Type: string

SubmissionFileLinkModel

Name

Type

Description

name

Type: string

Type: integer

SubmissionFileModel

Name

Type

Description

Type: integer

submissionId

Type: integer

name

Type: string

content

Type: string

SubmissionListModel

Name

Type

Description

submissions

Type: array of SubmissionModel

totalSubmissionCount

Type: integer

SubmissionModel

Name

Type

Description

Type: integer

dateTime

Type: date

userId

Type: integer

userDisplayName

Type: string

uploadedByUserId

Type: integer

uploadedByUserDisplayName

Type: string

exerciseId

Type: integer

exerciseName

Type: string

isPassive

Type: boolean

comment

Type: string

status

Type: SubmissionStatus

language

Type: Language

score

Type: number

result

Type: SubmissionResult

hiddenResult

Type: SubmissionResult

[Admin Only]

SubmissionsDay

Name

Type

Description

date

Type: date

count

Type: integer

SubmitModel

Name

Type

Description

Type: integer

userId

Type: integer

ignoreDue

Type: boolean

language

Type: Language

comment

Type: string

files

Type: array of FileModel

SubmitResultModel

Name

Type

Description

success

Type: boolean

submission

Type: SubmissionModel

SyncRequestModel

Name

Type

Description

files

Type: array of FileModel

filesKey

Type: string

syncLevel

Type: SyncLevel

At what level entities will be deleted

SyncResponseModel

Name

Type

Description

changelog

Type: string

filesKey

Type: string

syncCompleted

Type: boolean

errorOccured

Type: boolean

TemplateCopyModel

Name

Type

Description

name

Type: string

TemplateModel

Name

Type

Description

Type: integer

courseId

Type: integer

name

Type: string

created

Type: date

isInUse

Type: boolean

files

Type: array of FileModel

TestGroupModel

Name

Type

Description

Type: integer

exerciseId

Type: integer

name

Type: string

created

Type: date

[Admin Only]

priority

Type: integer

onTestGroupFailure

Type: OnTestGroupFailure

[Admin Only]

onTestGroupFailureGoto

Type: integer

[Admin Only]

runManually

Type: boolean

[Admin Only]

feedback

Type: TestGroupFeedback

generateOutStatus

Type: GenerateOutStatus

[Admin Only]

files

Type: array of FileModel

[Admin Only]

generatedFiles

Type: array of FileModel

[Admin Only]

TestGroupRunModel

Name

Type

Description

Type: integer

submissionId

Type: integer

testGroupId

Type: integer

testGroup

Type: TestGroupModel

grader

Type: string

[Admin Only]

created

Type: date

finished

Type: date

gradingStarted

Type: date

[Admin Only]

executionTime

Type: integer

[Admin Only]

priority

Type: integer

[Admin Only]

status

Type: TestGroupRunStatus

testRuns

Type: array of TestRunModel

result

Type: TestGroupRunResult

score

Type: number

log

Type: string

[Admin Only]

compilerOut

Type: string

TestModel

Name

Type

Description

testGroupId

Type: integer

name

Type: string

hint

Type: string

resultViews

Type: array of ResultViewModel

TestRunModel

Name

Type

Description

Type: integer

testGroupRunId

Type: integer

name

Type: string

cpuTime

Type: integer

wallTime

Type: integer

memory

Type: integer

result

Type: TestRunResult

judgeOutput

Type: string

judgeMachine

Type: string

score

Type: number

hint

Type: string

resultViews

Type: array of ResultViewModel

TextFileModel

Name

Type

Description

name

Type: string

content

Type: string

UserModel

Name

Type

Description

Type: integer

email

Type: string

name

Type: string

isAdministrator

Type: boolean

studentId

Type: string

Enums

ExerciseCollectionType

assignment | exerciseGroup

ExerciseField

GenerateOutStatus

noGeneration | generate | generating | failed | succeeded

Language

OnTestGroupFailure

break | continue | goto

ResultViewType

content | html | code | split | plot

SolutionVisibility

afterSolved | always | never

SubmissionResult

compilationError | testsFailed | succeeded | partlySucceeded

SubmissionStatus

SubmissionType

latestSubmission | bestSubmission

SyncLevel

course | exerciseCollection | exercise

TestField

result | score | time

TestGroupFeedback

full | resultAndJudgeOutput | onlyResult | hidden

TestGroupField

result | score | solvedTests | tests

TestGroupRunResult

compileError | testFailed | succeeded

TestGroupRunStatus

TestRunResult

UserCourseRole

user | author | administrator | noRole