Fetch one group challenge

GET

/v1/{organizationId}/group-challenge/{challengeId}

Bearer token
Permissiongroup-challenge/read
Per organization

Reads one group challenge of this organization: its dates, how many students a group takes, the grade groups it is open to and the steps a group works through, in order.

Parameters

Path parameters

Name	Type	Description
`organizationId`required	stringpattern `^[0-9a-f]{24}$`	The organization’s `_id`: 24 hexadecimal digits, as `listOrganizations` (`GET /v1/organization`) lists it. Example `64b7f0c2a1d3e4f5a6b7c8d9`
`challengeId`required	string	The group challenge’s `_id`, from `listGroupChallenges`.

Responses

200 OK

Success: message is "Group challenge fetched successfully.".

Body

successbooleanrequired
Always true on a success.
one oftrue
messagestringrequired
exampleGroup challenge fetched successfully.
dataobject · GroupChallengeResponserequired
A group challenge: groups of students, formed by their teacher, work through a set of steps between two dates.
11 fields of data
- _idstringrequired
  The challenge’s id: the challengeId of every other operation.
  example6650a1b2c3d4e5f6a7b8c9eb
- namestringrequired
  Its name.
  exampleSTEM Maker Challenge
- statusstringrequired
  published while it runs; closed once the organizers have closed it, when it is still readable and takes no more work. New values may be added; treat an unknown one as closed.
  one ofpublishedclosed
  examplepublished
- isOpenbooleanrequired
  Whether it takes work right now: published, and now is between windowStart and windowEnd.
  exampletrue
- windowStartstringrequired
  When it opens (UTC).
  formatdate-timeexample2026-10-01T00:00:00.000Z
- windowEndstringrequired
  When it closes (UTC), inclusive. Nothing is submitted after it: not a step, not the final work.
  formatdate-timeexample2026-12-21T23:59:59.999Z
- minStudentsobjectnullablerequired
  The fewest students a group may have.
  example2
- maxStudentsobjectnullablerequired
  The most students a group may have.
  example3
- isPaidbooleanrequired
  Whether taking part costs a fee. The teacher settles it in the panel when they create the group; this API neither shows nor takes it.
  examplefalse
- gradeGroupsarray of GroupChallengeGradeGroupResponserequired
  The grade groups, in their order.
  3 fields of each item
  _idstringrequired
  The grade group’s id within the challenge.
  example6650a1b2c3d4e5f6a7b8c9ec
  labelstringrequired
  Its name, for a person.
  exampleGroup 7-8-9
  gradesarray of GroupChallengeGradeResponserequired
  The grades it takes. A student whose grade is in none of the grade groups cannot join the challenge.
  2 fields of each item
  _idstringrequired
  The grade’s id, the same _id listGrades returns and a student’s grade holds.
  example6650a1b2c3d4e5f6a7b8c9d4
  nameobjectnullablerequired
  The grade’s name, as it was when the challenge was set up.
  example10
- stepsarray of GroupChallengeStepDefinitionResponserequired
  The steps, in their order.
  6 fields of each item
  _idstringrequired
  The step’s id: what submitGroupChallengeStep takes.
  example6650a1b2c3d4e5f6a7b8c9ee
  ordernumberrequired
  Its position, from 1. Steps open one after another.
  example1
  titlestringrequired
  Its title, for a person.
  exampleProject proposal
  fileTypesarray of stringrequired
  The file types a member may upload for it, by extension, such as pdf or mp4.
  example["pdf","docx"]
  maxFileBytesobjectnullablerequired
  The largest file a member may upload for it, in bytes.
  example20971520
  maxFilesobjectnullablerequired
  How many files the step holds at most.
  example1

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

{
  "success": true,
  "message": "Group challenge fetched successfully.",
  "data": {
    "_id": "6650a1b2c3d4e5f6a7b8c9eb",
    "name": "STEM Maker Challenge",
    "status": "published",
    "isOpen": true,
    "windowStart": "2026-10-01T00:00:00.000Z",
    "windowEnd": "2026-12-21T23:59:59.999Z",
    "minStudents": 2,
    "maxStudents": 3,
    "isPaid": false,
    "gradeGroups": [
      {
        "_id": "6650a1b2c3d4e5f6a7b8c9ec",
        "label": "Group 7-8-9",
        "grades": [
          {
            "_id": "6650a1b2c3d4e5f6a7b8c9d4",
            "name": "10"
          }
        ]
      }
    ],
    "steps": [
      {
        "_id": "6650a1b2c3d4e5f6a7b8c9ee",
        "order": 1,
        "title": "Project proposal",
        "fileTypes": [
          "pdf",
          "docx"
        ],
        "maxFileBytes": 20971520,
        "maxFiles": 1
      }
    ]
  }
}

400 Bad request

bad_request: challengeId is not 24 hexadecimal digits.

When

bad_request
challengeId is not 24 hexadecimal digits.

Example

{
  "error": {
    "code": "bad_request",
    "documentation_url": "https://hub.main-team.org/api/errors#bad_request",
    "message": "Invalid value for 'challengeId': expected ObjectId.",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

401 Unauthorized

unauthorized: The token is missing or malformed, is not signed with your account’s apiSecret, breaks the iat and exp rules, has expired or been revoked, or its account is not active. All of these answer the same.

When

unauthorized
The token is missing or malformed, is not signed with your account’s apiSecret, breaks the iat and exp rules, has expired or been revoked, or its account is not active. All of these answer the same.

Example

{
  "error": {
    "code": "unauthorized",
    "documentation_url": "https://hub.main-team.org/api/errors#unauthorized",
    "message": "Authentication is required or the provided credentials are invalid.",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

403 Forbidden

forbidden: The token is valid, but no role on your account allows group-challenge/read on the organization in the path, or a role denies it.

When

forbidden
The token is valid, but no role on your account allows group-challenge/read on the organization in the path, or a role denies it.

Example

{
  "error": {
    "code": "forbidden",
    "documentation_url": "https://hub.main-team.org/api/errors#forbidden",
    "message": "Insufficient role permissions",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

404 Not found

not_found: organizationId is not the _id of an organization.
not_found: Group challenges are not switched on for this organization. The answer is the one an unknown path gets; nothing was read.
not_found: No group challenge of this organization has this id, or it is not published: a draft, archived or deleted challenge answers the same.

When

not_found
organizationId is not the _id of an organization.
not_found
Group challenges are not switched on for this organization. The answer is the one an unknown path gets; nothing was read.
not_found
No group challenge of this organization has this id, or it is not published: a draft, archived or deleted challenge answers the same.

Example

{
  "error": {
    "code": "not_found",
    "documentation_url": "https://hub.main-team.org/api/errors#not_found",
    "message": "Organization not found!",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

429 Too many requests

too_many_requests: Your account has made more than 100 requests to this operation in the current 60-second window. Wait the seconds in Retry-After before sending again.

When

too_many_requests
Your account has made more than 100 requests to this operation in the current 60-second window. Wait the seconds in Retry-After before sending again.

Headers

Retry-After integer: Seconds to wait before sending again; a request sent sooner is refused too.

Example

{
  "error": {
    "code": "too_many_requests",
    "documentation_url": "https://hub.main-team.org/api/errors#too_many_requests",
    "message": "Too many requests to this operation. Wait the number of seconds in Retry-After, then try again.",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

500 Internal error

internal_error: Something failed on our side. Retry later, and quote request_id if it goes on.

When

internal_error
Something failed on our side. Retry later, and quote request_id if it goes on.

Example

{
  "error": {
    "code": "internal_error",
    "documentation_url": "https://hub.main-team.org/api/errors#internal_error",
    "message": "An unexpected error occurred.",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

Example request

# $TOKEN: a short-lived token you minted with your API key and secret
curl -sS 'https://api.main-team.org/v1/<organizationId>/group-challenge/<challengeId>' \
  -H "Authorization: Bearer $TOKEN"

const token = process.env.TOKEN; // a short-lived token you minted with your API key and secret

const res = await fetch('https://api.main-team.org/v1/<organizationId>/group-challenge/<challengeId>', {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);
console.log(body.data);

<?php
$token = getenv('TOKEN'); // a short-lived token you minted with your API key and secret

$ch = curl_init('https://api.main-team.org/v1/<organizationId>/group-challenge/<challengeId>');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
if ($response === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$body = json_decode($response, true);
if ($status >= 400) {
    $error = $body['error'];
    throw new RuntimeException("$status {$error['code']}: {$error['message']}");
}
print_r($body['data']);