Skip to main content

Internal API

See the backend API page for an explanation about how the API code is structured. All routes are found at the http://localhost:8000/api endpoint in development and the /api endpoint in production, which can be accessed on the frontend through the VITE_JURY_URL environmental variable.

An example request looks like the following:

const projRes = await getRequest<Project[]>('/project/list', 'admin');
if (projRes.status !== 200) {
    errorAlert(projRes);
    return;
}
set({ projects: projRes.data as Project[] });

Note that this uses the getRequest and errorAlert frontend methods, which are described in the calling backend API page.

All Routes​

All routes are listed in server/router/init.go with their respective handlers.

PathMethodAuthDescription
/GETHeartbeat route
/judge/loginPOSTLogin judge
/admin/loginPOSTLog into the admin dashboard
/judge/authPOSTjudgeChecks to see if judge is logged in
/admin/authPOSTadminChecks to see if admin is logged in
/judge/newPOSTadminAdd a new judge
/judge/csvPOSTadminAdd judges by CSV
/judge/listGETadminGet list of all judges
/judge/:idDELETEadminDeletes a judge by ID
/judge/:idPUTadminEdit judge info
/admin/groups/swapPOSTadminSwaps the judge groups manually
/admin/qrPOSTadminGenerate add judge QR code
/admin/qr/:trackPOSTadminGenerate add judge to track QR code
/admin/qrGETadminGets add judge QR code
/admin/qr/:trackGETadminGets add judge to track QR code
/qr/check/POSTCheck if QR code is right
/qr/check/:trackPOSTCheck if track QR code is right
/qr/addPOSTAdd judge from QR code
/project/newPOSTadminAdd a new project
/project/devpostPOSTadminUpload a Devpost CSV
/project/csvPOSTadminAdd projects by CSV
/project/listGETadminget list of all projects
/project/:idDELETEadminDelete project by ID
/project/:idPUTadminEdit project info
/admin/statsGETadminGet all stats
/admin/stats/:trackGETadminGet all stats for a track
/project/statsGETadminGet the stats for projects
/judge/statsGETadminGet the stats for judges
/admin/flagsGETadminGets all flags
/admin/clockGETadminGets the current clock state
/admin/clock/pausePOSTadminPauses the clock
/admin/clock/unpausePOSTadminResumes the clock
/admin/clock/backupPOSTadminBacks up the clock to the database
/admin/startedGETCheck if the clock is running
/admin/clock/resetPOSTadminResets the clock
/admin/resetPOSTadminResets the entire database
/project/reassignPOSTadminReassign all project table numbers
/project/balance-groupsPOSTadminBalances project group numbers
/project/reassignPOSTadminReassign all project table numbers
/admin/timerGETjudgeGets the judge timer length
/admin/optionsGETadminGets all config options set
/admin/optionsPOSTadminSets config options
/admin/tracksPOSTadminUpdate the list of tracks
/admin/track-viewsPOSTadminUpdate the min views per track
/admin/num-groupsPOSTadminSets num of groups and reassigns nums
/admin/group-sizesPOSTadminSets the size of groups and reassigns nums
/admin/block-reqsPOSTadminSets whether to block login requests
/admin/max-reqsPOSTadminSets the maximum number of logins/min
/admin/export/judgesGETadminExports judges as a CSV
/admin/export/projectsGETadminExports projects as a CSV
/admin/export/challengesGETadminExports projects by challenge as ZIP of CSVs
/admin/export/rankingsGETadminExports a list of rankings for each judge
/judge/hide/:idPUTadminHides a judge
/project/hide/:idPUTadminHides a project
/judge/move/group/:idPUTadminMoves a judge to a different group
/project/move/group/:idPUTadminMoves a project to a different group
/project/move/:idPUTadminMoves a project to a different table number
/project/prioritize/:idPUTadminPrioritizes a project
/project/prioritizePOSTadminPrioritizes multiple projects
/judge/hidePOSTadminHides multiple judges
/project/hidePOSTadminHides multiple projects
/judge/move/groupPOSTadminMoves multiple judges to a different group
/project/move/groupPOSTadminMoves multiple projects to a different group
/admin/flag/:idDELETEadminRemoves a flag
/admin/deliberationPOSTadminToggles deliberation mode
/admin/logGETadminGets the audit log
/judgeGETjudgeGets judge from token cookie
/judge/welcomeGETjudgeChecks for read_welcome for a judge
/judge/welcomePUTjudgeSet read_welcome to true for a judge
/judge/projectsGETjudgeGets the list of projects a judge has seen
/judge/nextPOSTjudgeGet next project for judge to view
/judge/skipPOSTjudgeSkips the current project with a reason
/judge/finishPOSTjudgeFinish viewing a project
/judge/rankPOSTjudgeUpdate judge rankings
/judge/star/:idPUTjudgeUpdate star ranking for a project
/judge/notes/:idPUTjudgeUpdate notes for a project
/project/:idGETjudgeGets a project by ID
/project/countGETjudgeGets the total number of projects
/judge/project/:idGETjudgeGets a judged project by a judge
/judge/deliberationGETjudgeReturns if deliberation mode is on
/project/list/publicGETGets a list of all projects for expo
/challengesGETGets a list of all challenges
/group-infoGETGets a list of all group names

Response Types​

OK Response​

Will return either as a success or failure. This will be represented with the following JSON, where 0 is failure and 1 is success.

{
    "ok": 1
}

Error Response​

All errors will be formatted in the following JSON:

{
    "error": "error string"
}

Default Routes​

Errors will return with a non-success status (generally 4xx).

GET /​

Heartbeat route

  • Auth: none
  • Response: OK response

Login Routes​

POST /judge/login​

Login judge

  • Auth: none
  • Body: JSON
{
    "code": "String | login code"
}
  • Response: JSON
{
    "token": "String | judge login token"
}

POST /admin/login​

Log into the admin dashboard

  • Auth: none
  • Body: JSON
{
    "password": "String | admin password"
}
  • Response: OK response

POST /judge/auth​

Checks to see if judge is logged in

  • Auth: judge
  • Response: OK response

POST /admin/auth​

Checks to see if admin is logged in

  • Auth: admin
  • Response: OK response

Admin Panel (Judges) Routes​

POST /judge/new​

Add a new judge

  • Auth: admin
  • Body: JSON
{
    "name": "String",
    "email": "String",
    "notes": "String"
}
  • Response: OK response

POST /judge/csv​

Add judges by CSV

  • Auth: admin
  • Body: FormData
    • csv: CSV file
    • hasHeader: Boolean, true if CSV has a header
    • noSend: Don't send email to judge if true
  • Response: OK response

GET /judge/list​

Get list of all judges

  • Auth: admin
  • Response: JSON List
[
    {
        "id": "ObjectId",
        "token": "String",
        "code": "String",
        "name": "String",
        "email": "String",
        "active": "bool",
        "track": "String",
        "group": "String",
        "read_welcome": "bool",
        "notes": "String",
        "current": "ObjectId",
        "last_location": "int",
        "seen": "int",
        "group_seen": "int",
        "seen_projects": [
            {
                "project_id": "ObjectID",
                "starred": "bool",
                "notes": "String",
                "name": "String",
                "location": "int",
                "description": "String"
            }
        ],
        "rankings": ["ObjectId", "ObjectId | and so on for each ranked project"],
        "last_activity": "DateTime"
    }
]

DELETE /judge/:id​

Deletes a judge by ID

  • Auth: admin
  • Parameter: ID, the ID of the judge to delete
  • Response: OK response

PUT /judge/:id​

Edit judge info

  • Auth: admin
  • Body: JSON
{
    "name": "String",
    "email": "String",
    "notes": "String"
}
  • Response: OK response

POST /admin/groups/swap​

Swaps the judge groups manually

  • Auth: admin
  • Response: OK response

POST /admin/qr​

Generate add judge QR code

  • Auth: admin
  • Response: JSON
{
    "qr_code": "String"
}

POST /admin/qr/:track​

Generate add judge to track QR code

  • Auth: admin
  • Response: JSON
{
    "qr_code": "String"
}

GET /admin/qr​

Gets add judge QR code

  • Auth: none
  • Response: JSON
{
    "qr_code": "String"
}

GET /admin/qr/:track​

Gets add judge to track QR code

  • Auth: none
  • Response: JSON
{
    "qr_code": "String"
}

POST /qr/check​

Checks if QR code is correct

  • Auth: none
  • Body: JSON
{
    "code": "String"
}
  • Response: OK response

POST /qr/check/:track​

Checks if track QR code is correct

  • Auth: none
  • Body: JSON
{
    "code": "String"
}
  • Response: OK response

POST /qr/add​

Add judge from QR code

  • Auth: none
  • Body: JSON
{
    "name": "String",
    "email": "String",
    "notes": "String",
    "code": "String | QR code token"
}
  • Response: OK response

Admin Panel (Projects) Routes​

POST /project/new​

Add a new project

  • Auth: admin
  • Body: JSON
{
    "name": "String",
    "description": "String",
    "url": "String",
    "try_link": "String",
    "video_link": "String",
    "challenge_list": "String | comma-separated list of challenges/tracks"
}
  • Response: OK response

POST /project/devpost​

Upload a Devpost CSV

  • Auth: admin
  • Body: FormData
    • csv: CSV file
  • Response:

POST /project/csv​

Add projects by CSV

  • Auth: admin
  • Body: FormData
    • csv: CSV file
    • hasHeader: Boolean, true if CSV has a header
  • Response: OK response

GET /project/list​

get list of all projects

  • Auth: admin
  • Response: JSON
[
    {
        "id": "ObjectId",
        "name": "String",
        "location": "u64",
        "description": "String",
        "url": "String",
        "try_link": "String",
        "video_link": "String",
        "challenge_list": ["String"],
        "seen": "int",
        "track_seen": {
            "track1": "int",
            "track2": "int"
        },
        "score": "int",
        "stars": "int",
        "track_stars": {
            "track1": "int",
            "track2": "int"
        },
        "active": "bool",
        "prioritized": "bool",
        "group": "int",
        "last_activity": "DateTime"
    }
]

DELETE /project/:id​

Delete project by ID

  • Auth: admin
  • Parameter: ID of project to delete
  • Response: OK response

PUT /project/:id​

Edit project info

  • Auth: admin
  • Body: JSON
{
    "name": "String",
    "description": "String",
    "url": "String",
    "try_link": "String",
    "video_link": "String",
    "challenge_list": "String | comma-separated list of challenges/tracks"
}
  • Response: OK response

Admin Panel (Stats/Data) Routes​

GET /admin/stats​

Get all stats

  • Auth: admin
  • Response: JSON
{
    "projects": "int",
    "avg_project_seen": "int",
    "avg_judge_seen": "int",
    "judges": "int"
}

GET /admin/stats/:track​

Get all stats for a track

  • Auth: admin
  • Parameter: Track, the track to fetch stats for
  • Response: JSON
{
    "projects": "int",
    "avg_project_seen": "int",
    "avg_judge_seen": "int",
    "judges": "int"
}

GET /project/stats​

Get the stats for projects

  • Auth: admin
  • Response: JSON
{
    "num": "int",
    "num_active": "int",
    "avg_seen": "float"
}

GET /judge/stats​

Get the stats for judges

  • Auth: admin
  • Response: JSON
{
    "num": "int",
    "num_active": "int",
    "avg_seen": "float"
}

GET /admin/flags​

Gets all flags

  • Auth: admin
  • Response: JSON List
[
    {
        "id": "ObjectID",
        "project_id": "ObjectID",
        "judge_id": "ObjectID",
        "time": "DateTime",
        "project_name": "String",
        "project_location": "int",
        "judge_name": "String",
        "reason": "String"
    }
]

Admin Panel (Clock) Routes​

GET /admin/clock​

Gets the current clock state

  • Auth: admin
  • Response: JSON
{
    "running": "bool",
    "time": "int"
}

POST /admin/clock/pause​

Pauses the clock

  • Auth: admin
  • Response: OK response

POST /admin/clock/unpause​

Resumes the clock

  • Auth: admin
  • Response: OK response

POST /admin/clock/backup​

Backs up the clock to the database

  • Auth: admin
  • Response: OK response

GET /admin/started​

Check if the clock is running

  • Auth: admin
  • Response: OK response (1 if true)

Admin Options/Settings Routes​

POST /admin/clock/reset​

Resets the clock

  • Auth: admin
  • Response: OK response

POST /admin/reset​

Resets the entire database

  • Auth: admin
  • Response: OK response

POST /project/reassign​

Reassign all project table numbers

  • Auth: admin
  • Response: OK response

POST /project/balance-groups​

Balances project group numbers

  • Auth: admin
  • Response: OK response

POST /project/reassign​

Reassign all project table numbers

  • Auth: admin
  • Response: OK response

GET /admin/timer​

Gets the judge timer length

  • Auth: admin
  • Response: JSON
{
    "judging_timer": "int"
}

GET /admin/options​

Gets all config options set

  • Auth: admin
  • Response: JSON
{
    "id": "ObjectID",
    "ref": "int",
    "clock": {
        "start_time": "int",
        "pause_time": "int",
        "running": "bool"
    },
    "judging_timer": "int",
    "min_views": "int",
    "clock_sync": "bool",
    "deliberation": "bool",
    "judge_tracks": "bool",
    "tracks": ["String"],
    "multi_group": "bool",
    "num_groups": "int",
    "group_sizes": ["int"],
    "switching_mode": "String",
    "auto_switch_prop": "float",
    "manual_switches": "int",
    "qr_code": "String",
    "track_qr_codes": {
        "track1": "String",
        "track2": "String"
    },
    "group_names": ["String"],
    "ignore_tracks": ["String"],
    "max_req_per_min": "int",
    "block_reqs": "bool"
}

POST /admin/options​

Sets config options

  • Auth: admin
  • Body: JSON
{
    "judging_timer": "int",
    "min_views": "int",
    "clock_sync": "bool",
    "judge_tracks": "bool",
    "tracks": ["String"],
    "multi_group": "bool",
    "num_groups": "int",
    "group_sizes": ["int"],
    "switching_mode": "String",
    "auto_switch_prop": "float",
    "group_names": ["String"],
    "ignore_tracks": ["String"],
    "max_req_per_min": "int",
    "block_reqs": "bool"
}
  • Response: OK response

POST /admin/tracks​

Update the list of tracks

  • Auth: admin
  • Body: JSON
{
    "tracks": ["String"]
}
  • Response: OK response

POST /admin/track-views​

Update the min views per track

  • Auth: admin
  • Body: JSON
{
    "track_views": ["int"]
}
  • Response: OK response

POST /admin/num-groups​

Sets num of groups and reassigns nums

  • Auth: admin
  • Body: JSON
{
    "num_groups": "int"
}
  • Response: OK response

POST /admin/group-sizes​

Sets the size of groups and reassigns nums

  • Auth: admin
  • Body: JSON
{
    "group_sizes": ["int"]
}
  • Response: OK response

POST /admin/block-reqs​

Sets whether to block login requests

  • Auth: admin
  • Body: JSON
{
    "block_reqs": "bool"
}
  • Response: OK response

POST /admin/max-reqs​

Sets the maximum number of logins/min

  • Auth: admin
  • Body: JSON
{
    "max_req_per_min": "int"
}
  • Response:

Admin Export Routes​

GET /admin/export/judges​

Exports judges as a CSV

  • Auth: admin
  • Response: CSV Blob

GET /admin/export/projects​

Exports projects as a CSV

  • Auth: admin
  • Response: CSV Blob

GET /admin/export/challenges​

Exports projects by challenge as ZIP of CSVs

  • Auth: admin
  • Response: ZIP Blob

GET /admin/export/rankings​

Exports a list of rankings for each judge

  • Auth: admin
  • Response: CSV Blob

Admin Table Actions Routes​

PUT /judge/hide/:id​

Hides a judge

  • Auth: admin
  • Parameter: ID | judge ID to hide
  • Response: OK response

PUT /project/hide/:id​

Hides a project

  • Auth: admin
  • Parameter: ID | judge ID to hide
  • Response: OK response

PUT /judge/move/group/:id​

Moves a judge to a different group

  • Auth: admin
  • Parameter: ID | judge ID to hide
  • Body: JSON
{
    "group": "int | group number"
}
  • Response: OK response

PUT /project/move/group/:id​

Moves a project to a different group

  • Auth: admin
  • Parameter: ID | ID of project to move
  • Body: JSON
{
    "group": "int | group number"
}
  • Response: OK response

PUT /project/move/:id​

Moves a project to a different table number

  • Auth: admin
  • Parameter: ID | ID of project to move
  • Body: JSON
{
    "location": "int"
}
  • Response: OK response

PUT /project/prioritize/:id​

Prioritizes a project

  • Auth: admin
  • Parameter: ID | ID of project to prioritize
  • Body: JSON
{
    "prioritize": "bool | true if prioritizing"
}
  • Response: OK response

POST /project/prioritize​

Prioritizes multiple projects

  • Auth: admin
  • Body: JSON
{
    "items": ["ObjectID"],
    "prioritize": "bool | true if prioritizing"
}
  • Response: OK response

POST /judge/hide​

Hides multiple judges

  • Auth: admin
  • Body: JSON
{
    "items": ["ObjectID"],
    "hide": "bool | true if hiding"
}
  • Response: OK response

POST /project/hide​

Hides multiple projects

  • Auth: admin
  • Body: JSON
{
    "items": ["ObjectID"],
    "hide": "bool | true if hiding"
}
  • Response: OK response

POST /judge/move/group​

Moves multiple judges to a different group

  • Auth: admin
  • Body: JSON
{
    "items": ["ObjectID"],
    "group": "int | group number"
}
  • Response: OK response

POST /project/move/group​

Moves multiple projects to a different group

  • Auth: admin
  • Body: JSON
{
    "items": ["ObjectID"],
    "group": "int | group number"
}
  • Response: OK response

DELETE /admin/flag/:id​

Removes a flag

  • Auth: admin
  • Parameter: ID, the ID of the flag to delete
  • Response: OK response

POST /admin/deliberation​

Toggles deliberation mode

  • Auth: admin
  • Body: JSON
{
    "start": "bool | true if starting deliberation"
}
  • Response: OK response

Admin Panel (Log) Routes​

GET /admin/log​

Gets the audit log

  • Auth: admin
  • Response: JSON
{
    "log": "String"
}

Judging Routes​

GET /judge​

Gets judge from token cookie

  • Auth: judge
  • Response: JSON
{
    "id": "ObjectId",
    "token": "String",
    "code": "String",
    "name": "String",
    "email": "String",
    "active": "bool",
    "track": "String",
    "group": "String",
    "read_welcome": "bool",
    "notes": "String",
    "current": "ObjectId",
    "last_location": "int",
    "seen": "int",
    "group_seen": "int",
    "seen_projects": [
        {
            "project_id": "ObjectID",
            "starred": "bool",
            "notes": "String",
            "name": "String",
            "location": "int",
            "description": "String"
        }
    ],
    "rankings": ["ObjectId", "ObjectId | and so on for each ranked project"],
    "last_activity": "DateTime"
}

GET /judge/welcome​

Checks for read_welcome for a judge

  • Auth: judge
  • Response: OK response

PUT /judge/welcome​

Set read_welcome to true for a judge

  • Auth: judge
  • Response: OK response

GET /judge/projects​

Gets the list of projects a judge has seen

  • Auth: judge
  • Response: JSON List
[
    {
        "project_id": "ObjectID",
        "name": "String",
        "location": "int",
        "description": "String",
        "notes": "String",
        "starred": "bool",
        "url": "String"
    }
]

POST /judge/next​

Get next project for judge to view

  • Auth: judge
  • Response: JSON
{
    "project_id": "ObjectID"
}

POST /judge/skip​

Skips the current project with a reason

  • Auth: judge
  • Body: JSON
{
    "reason": "String"
}
  • Response: OK response

POST /judge/finish​

Finish viewing a project

  • Auth: judge
  • Body: JSON
{
    "notes": "String",
    "starred": "bool"
}
  • Response: OK response

POST /judge/rank​

Update judge rankings

  • Auth: judge
  • Body: JSON
{
    "ranking": ["ObjectID"]
}
  • Response: OK response

PUT /judge/star/:id​

Update star ranking for a project

  • Auth: judge
  • Body: JSON
{
    "starred": "bool"
}
  • Response: OK response

PUT /judge/notes/:id​

Update notes for a project

  • Auth: judge
  • Parameter: ID | ID for project to update notes for
  • Body: JSON
{
    "notes": "String"
}
  • Response: OK response

GET /project/:id​

Gets a project by ID

  • Auth: judge
  • Parameter: ID | ID for project to get
  • Response: JSON
{
    "id": "ObjectId",
    "name": "String",
    "location": "u64",
    "description": "String",
    "try_link": "String",
    "video_link": "String",
    "challenge_list": ["String"],
    "seen": "u64",
    "votes": "u64",
    "mu": "f64",
    "sigma_sq": "f64",
    "active": "bool",
    "prioritized": "bool",
    "last_activity": "DateTime"
}

GET /project/count​

Gets the total number of projects

  • Auth: judge
  • Response: JSON
{
    "count": "int"
}

GET /judge/project/:id​

Gets a judged project by a judge

  • Auth: judge
  • Parameter: ID | Project ID to get
  • Response: JSON
{
    "project_id": "ObjectID",
    "name": "String",
    "location": "int",
    "description": "String",
    "notes": "String",
    "starred": "bool",
    "url": "String"
}

GET /judge/deliberation​

Returns if deliberation mode is on

  • Auth: judge
  • Response: OK response | 1 if deliberation mode is on

Project Expo Routes​

GET /project/list/public​

Gets a list of all projects for expo

  • Auth: none
  • Response: JSON List
[
    {
        "name": "String",
        "location": "u64",
        "description": "String",
        "url": "String",
        "try_link": "String",
        "video_link": "String",
        "challenge_list": ["String"],
        "group": "int"
    }
]

GET /challenges​

Gets a list of all challenges

  • Auth: none
  • Response: JSON List
["String | challenge 1", "String | challenge 2"]

GET /group-info​

Gets a list of all group names and if groups are enabled

  • Auth: none
  • Response: JSON
{
    "names": ["String | group 1", "String | group 2"],
    "enabled": "bool"
}