Challenges

Source: apps/api/src/routes/client/challenges.ts.

Endpoints

Method	Path	Description
GET	`/client/challenges`	Currently-active challenges with user progress + join status.
POST	`/client/challenges/:challengeId/join`	Join a challenge. Idempotent — returns existing row if already joined.
GET	`/client/challenges/mine`	User's challenges (active and completed) with challenge definition metadata.

GET /client/challenges

Active = is_active = true AND start_at <= NOW() AND end_at >= NOW().

Response 200

{
  "data": [
    {
      "id": "…",
      "name": "…",
      "start_at": "…",
      "end_at": "…",
      "goal_type": "…",
      "goal_value": 10,
      "reward_xp": 100,
      "user_progress": 3,
      "user_status": "active",
      "user_completed_at": null,
      "is_joined": true
    }
  ]
}

Errors

500 FETCH_FAILED.

Try it:

GET/client/challenges

client auth

curl -X GET 'https://api.amba.dev/client/challenges'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/client/challenges' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}'

POST /client/challenges/:challengeId/join

Insert into user_challenges with progress = 0, status = 'active'. Idempotent.

Response 201 (newly joined) / 200 (already joined)

{ "data": { "app_user_id": "…", "challenge_id": "…", "progress": 0, "status": "active" } }

Errors

404 NOT_FOUND — challenge doesn't exist or isn't active.
500 CREATE_FAILED.

Try it:

POST/client/challenges/%7B%7BchallengeId%7D%7D/join

client auth

curl -X POST 'https://api.amba.dev/client/challenges/%7B%7BchallengeId%7D%7D/join'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/client/challenges/{challengeId}/join' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET /client/challenges/mine

All of the caller's user_challenges, newest first, joined to the challenge definition.

Response 200

{
  "data": [
    {
      "app_user_id": "…",
      "challenge_id": "…",
      "progress": 3,
      "status": "active",
      "completed_at": null,
      "challenge_definitions": {
        "name": "…",
        "goal_type": "…",
        "goal_value": 10,
        "start_at": "…",
        "end_at": "…",
        "reward_xp": 100
      }
    }
  ]
}

Try it:

GET/client/challenges/mine

client auth

curl -X GET 'https://api.amba.dev/client/challenges/mine'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/client/challenges/mine' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}'

On this page