View source for API Judging Scores

== Judging Scores ==
Two related endpoints:

# '''Upload scores''' — <code>POST /api/data/JudgingScores</code> (also documented at [[API Upload Judging Score]])
# '''Get scores for a round''' — <code>POST /api/data/JudgingScoresForRound</code>

=== Authentication ===
All data API calls are <code>POST</code> (unless noted) with JSON body:

{| class="wikitable"
|-
! Field !! Required !! Description
|-
| <code>ApiKey</code> || Yes* || Private API key for your site. Prefer this over username/password.
|-
| <code>Username</code> / <code>Password</code> || Yes* || Alternate auth if not using ApiKey.
|-
| <code>FairId</code> || Yes || Fair GUID from the site URL (<code>f</code> query parameter).
|-
| <code>Body</code> || Depends || Request payload. Use <code>{}</code> when no body fields are needed.
|}

* Provide '''either''' <code>ApiKey</code> '''or''' <code>Username</code>+<code>Password</code>.

Calls must be run '''server-side''' — do not expose your API key in a browser.

=== Response envelope ===
Most endpoints return:

<pre>
{
  Success: true,
  Message: null,   // error text when Success is false
  Body: { ... }    // endpoint-specific payload
}
</pre>


=== Upload scores ===
See [[API Upload Judging Score]] for the full request shape (<code>RoundId</code>, <code>ClearOldScores</code>, <code>Assignments</code> with <code>ProjectKey</code>, <code>JudgeId</code>, <code>Score</code>, <code>Notes</code>).

=== Get scores for a round ===
<syntaxhighlight lang="JavaScript" line>
fetch('/api/data/JudgingScoresForRound', {
    method:'POST',
    headers:{'Content-Type': 'application/json'},
    body: JSON.stringify({
            ApiKey:'<Private key>',
            FairId: '9df61f13-474b-442f-ac1f-edca7348ef71',
            Body: {
				RoundId: 2,
				ClearOldScores: false  // WARNING: if true this CLEARS scores before reading
			}
        })
})
.then(response => response.json())
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});
</syntaxhighlight>

==== Response ====
<syntaxhighlight lang="JavaScript">
{
  Success: true,
  Message: null,
  Body: [{
    ProjectId: "AB-100",
    At: "2024-03-15T10:00:00",  // adjusted to fair timezone
    Score: 95.5,
    Notes: "Strong methodology",
    NoShow: false,
    Rubric: "Main Rubric",
    ScoreBreakdown: [
      { Id: "q1", Name: "Scientific method", Score: "5" }
    ],
    JudgeId: 9001,
    JudgePublicId: "judge-public-guid",
    JudgeName: "Sam Judge"
  }]
}
</syntaxhighlight>

=== Field notes ===
* Round ids come from [[API Get Info]] → <code>Rounds</code>.
* On the get endpoint, <code>ClearOldScores: true</code> will clear the round scores before returning results — leave it false unless you intend to wipe scores.
* Score breakdown is only returned when rubric detail data is available for the assessment.

=== Related APIs ===
* [[API Upload Judging Score]]
* [[API Set Judging Assignments]]
* [[API Get Judges]] / [[API Get Projects]] / [[API Get Info]]

<br/><br/>
[[Category: API]]