Skip to content
Olympiads Hub
API documentation
View as MarkdownOpen in Claude

Group challenges

Submit one step of a group for one of your students

POST
/v1/{organizationId}/group-challenge/{challengeId}/group/{groupId}/step/{stepId}/submit
Try it in the sandbox

Submits the open step of a group, for one of your students who is a member of it, exactly as the student would in the panel: the files uploaded for the step are submitted with it, and the next step opens. The members upload the work in the panel or the app; this API does not upload. Read the group first: a step’s canSubmit says whether this would be accepted now.

The body names the student you act for: { "studentId": "<studentId>" }. The group’s history records the submit as your account (partner) acting for them.

Checks, in order. The first that fails decides the answer, and nothing is written for any of them.

  1. The student is yours (404), and has signed in to this organization once (409).
  2. The challenge exists and is published or closed (404).
  3. The group belongs to the challenge and the student is an active member of it (404).
  4. The step has not been submitted already. If it has, the answer is 200 with changed: false and "Step already submitted.", and nothing changes, so a retry after a timeout is safe.
  5. The challenge is published (409, challenge_closed) and now is between windowStart and windowEnd (409, window_closed).
  6. The teacher has confirmed the group (409, payment_pending or group_not_confirmed).
  7. The group has this step (404).
  8. The step is open, not locked (409, step_locked).
  9. At least one file has been uploaded for it (409, step_empty). Do not retry this one in a loop: a member uploads the work first.

Every 409 carries error.details.reason, one of the codes above; branch on it, not on the message.

Side effects. The step becomes submitted, and its uploaded files with it. An upload still running for the step is stopped. The next step, if there is one, opens. An entry is added to the group’s history, and a second one when the next step opens.

Busy. A group is changed by one request at a time. If someone is changing it at that moment the answer is 503 with Retry-After: 1 and details.reason: busy, and nothing was written: send the same request again.

Parameters

Path parameters

NameTypeDescription
organizationIdrequiredstringpattern ^[0-9a-f]{24}$

The organization’s _id: 24 hexadecimal digits, as listOrganizations (GET /v1/organization) lists it.

Example 64b7f0c2a1d3e4f5a6b7c8d9

challengeIdrequiredstring

The group challenge’s _id, from listGroupChallenges.

groupIdrequiredstring

The group’s _id, from listGroupChallengeGroups or a student’s group.

stepIdrequiredstring

The step’s _id, from the group’s steps (getGroupChallengeGroup) or the challenge’s.

Request body

application/jsonrequired

  • studentIdstringrequired

    The student the submit is made for: their _id, as registerStudent returned it. They must be one of your students and an active member of the group; the group’s log records the submit as your account acting for them.

    example6650a1b2c3d4e5f6a7b8c9d0

Responses

200 OK

Success: message is "Step submitted.".

Or message is "Step already submitted.": The step had already been submitted, by anyone. changed is false and nothing changed.

Body

  • successbooleanrequired

    Always true on a success.

    one oftrue

  • messagestringrequired

    exampleStep submitted.

  • dataobject · GroupChallengeStepSubmitResponserequired

    A step submitted for one of your students.

    5 fields of data

    • groupIdstringrequired

      The group’s id.

      example6650a1b2c3d4e5f6a7b8c9ed

    • groupStatusstringrequired

      The group’s state now: finalized while steps remain open.

      one ofawaiting_paymentdraftfinalizedcompleted

      examplefinalized

    • stepobject · GroupChallengeSubmittedStepResponserequired

      The step you submitted.

      4 fields of step

      • _idstringrequired

        The step’s id.

        example6650a1b2c3d4e5f6a7b8c9ee

      • orderobjectnullablerequired

        Its position, from 1.

        example1

      • statestringrequired

        Always submitted.

        one ofsubmitted

      • submittedAtstringnullablerequired

        When it was submitted: now, or the first time on a repeat.

        formatdate-timeexample2026-10-20T16:02:11.000Z

    • nextStepobject · GroupChallengeOpenedStepResponsenullablerequired

      The step this submit opened, or null when it was the last one, or on a repeat.

      3 fields of nextStep

      • _idstringrequired

        The step’s id.

        example6650a1b2c3d4e5f6a7b8c9f1

      • ordernumberrequired

        Its position.

        example2

      • statestringrequired

        Always open: the group can work on it now.

        one ofopen

    • changedbooleanrequired

      true when this request submitted the step; false when it had already been submitted, and nothing changed.

      exampletrue

Headers

X-RateLimit-Limit integer

Requests your account may make to this operation per window (100).

X-RateLimit-Remaining integer

Requests left in the current window.

X-RateLimit-Reset integer

Seconds until the current window ends.

Example

{
  "data": {
    "changed": true,
    "groupId": "6650a1b2c3d4e5f6a7b8c9ed",
    "groupStatus": "finalized",
    "nextStep": {
      "_id": "6650a1b2c3d4e5f6a7b8c9f1",
      "order": 2,
      "state": "open"
    },
    "step": {
      "_id": "6650a1b2c3d4e5f6a7b8c9ee",
      "order": 1,
      "state": "submitted",
      "submittedAt": "2026-10-20T16:02:11.000Z"
    }
  },
  "message": "Step submitted.",
  "success": true
}

Example request

# $TOKEN: a short-lived token you minted with your API key and secret
curl -sS -X POST 'https://api.main-team.org/v1/<organizationId>/group-challenge/<challengeId>/group/<groupId>/step/<stepId>/submit' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "studentId": "6650a1b2c3d4e5f6a7b8c9d0"
}
JSON

Search the API documentation

Guides, endpoints by name, path or permission, and error codes such as not_found.