All endpoints are prefixed with
/api/challenges. Responses use
Content-Type: application/json. Creating a challenge requires an admin
Bearer token.GET /api/challenges
Return a paginated list of all challenges. Optionally filter by difficulty or search term.Query parameters
Page number for pagination. Defaults to
1.Number of challenges per page. Defaults to
20, maximum 100.Filter by difficulty level. One of
easy, medium, or hard.Case-insensitive keyword search against challenge title and description.
Maximum 100 characters.
Response — 200 OK
true on success.Array of challenge objects.
Error responses
| Status | Condition |
|---|---|
400 | Invalid query parameters (e.g. unknown difficulty value) |
Example
GET /api/challenges/nearby
Return challenges within a given radius of the provided GPS coordinates, sorted by distance ascending (closest first).Query parameters
The user’s current latitude (
-90 to 90).The user’s current longitude (
-180 to 180).Search radius in meters. Defaults to
5000. Maximum 50000.Page number. Defaults to
1.Items per page. Defaults to
20, maximum 100.Response — 200 OK
true on success.Challenges within the specified radius, sorted by distance ascending.
Error responses
| Status | Condition |
|---|---|
400 | latitude or longitude missing, or values out of range |
Example
GET /api/challenges/:id
Return a single challenge by its ID, including the total number of completions.Path parameters
The numeric ID of the challenge.
Response — 200 OK
true on success.Error responses
| Status | Condition |
|---|---|
400 | id is not a valid integer |
404 | No challenge found with that ID |
Example
POST /api/challenges
Create a new challenge. Returns the newly created challenge object.Auth required: Yes, admin only — include
Authorization: Bearer <accessToken>.
The authenticated user must have the admin role.Request body
Challenge title. 1–200 characters. Must be unique.
Challenge description. 1–1000 characters.
GPS latitude of the challenge location (
-90 to 90).GPS longitude of the challenge location (
-180 to 180).One of
easy, medium, or hard.Positive integer representing the aura points awarded on completion.
Response — 201 Created
true on success."Challenge created successfully"Error responses
| Status | Condition |
|---|---|
400 | Validation error (missing field, out-of-range value, invalid difficulty) |
401 | Missing or invalid Bearer token |
403 | Authenticated user does not have the admin role |
409 | A challenge with the same title already exists |