Challenges

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().

event_name is the event an event_count challenge counts, and null on the other goal types. user_progress on an event_count challenge is the number of events with that name the caller tracked since start_at. user_progress and user_status catch up within about 5 minutes of the activity that moves them.

Response 200

{
  "data": [
    {
      "id": "…",
      "name": "…",
      "start_at": "…",
      "end_at": "…",
      "goal_type": "event_count",
      "goal_value": 10,
      "event_name": "workout_completed",
      "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/v1/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

Join the challenge 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/v1/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 challenges the caller has joined, newest first, with each row carrying the challenge definition inlined.

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/v1/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