Challenges

Challenges are time-bounded goals (start_at → end_at) that users join and make progress against. Per-user join records track each user's progress and completion state.

Endpoints

POST /admin/projects/:projectId/challenges

Request

event_name is the name of the event an event_count challenge counts. A participant's progress is the number of events they tracked with exactly that name between start_at and end_at. It is 1 to 255 characters, with no leading or trailing whitespace.

Response 201

{
  "data": {
    "id": "…",
    "name": "10 workouts this week",
    "goal_type": "event_count",
    "goal_value": 10,
    "event_name": "workout_completed",
    "reward_xp": 100,
    "start_at": "…",
    "end_at": "…"
  }
}

Errors

• 400 VALIDATION_ERROR with details.field: "event_name": an event_count challenge without event_name, a malformed event_name, or event_name on another goal type.
• 503 TENANT_MIGRATION_PENDING: the project is still being updated to store challenge event names. Retry in a few minutes.

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/challenges' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Five workouts this week",
  "start_at": "2030-01-07T00:00:00Z",
  "end_at": "2030-01-14T00:00:00Z",
  "goal_type": "event_count",
  "goal_value": 5,
  "event_name": "workout_completed"
}'

Curl:

curl -X POST "${BASE_URL}/admin/projects/${PROJECT_ID}/challenges" \
  -H "Authorization: Bearer ${DEV_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Five workouts this week","start_at":"2030-01-07T00:00:00Z","end_at":"2030-01-14T00:00:00Z","goal_type":"event_count","goal_value":5,"event_name":"workout_completed"}'

GET /admin/projects/:projectId/challenges

Query

Response 200

{
  "data": [
    { "id": "…", "name": "…", "start_at": "…", "end_at": "…", "goal_type": "…", "goal_value": 10 }
  ]
}

Try it:

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/challenges'

Curl:

curl -X GET "${BASE_URL}/admin/projects/${PROJECT_ID}/challenges" \
  -H "Authorization: Bearer ${DEV_TOKEN}"

GET /admin/projects/:projectId/challenges/:challengeId

Errors

• 404 NOT_FOUND.

Try it:

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/challenges/%7B%7BchallengeId%7D%7D'

Curl:

curl -X GET "${BASE_URL}/admin/projects/${PROJECT_ID}/challenges/{challengeId}" \
  -H "Authorization: Bearer ${DEV_TOKEN}"

PATCH /admin/projects/:projectId/challenges/:challengeId

Allowed fields: name, description, start_at, end_at, goal_type, goal_value, event_name, reward_xp, reward_achievement_id, is_active.

event_name follows the same rules as on create, applied to the challenge the update produces:

• Set event_name on an event_count challenge that has none to turn it on. An event_count challenge created before event names existed has event_name: null; it is skipped and never completes until you set one.
• An event_count challenge keeps its event_name: event_name: null is rejected. Set is_active: false to stop the challenge instead.
• Changing goal_type to event_count requires an event_name, in the same request or already stored.
• Changing goal_type to another type clears event_name.

Errors

• 400 VALIDATION_ERROR with details.field: "event_name".
• 404 NOT_FOUND.
• 503 TENANT_MIGRATION_PENDING when the update stores an event_name and the project is still being updated. Retry in a few minutes.

Try it:

curl -X PATCH 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/challenges/%7B%7BchallengeId%7D%7D'

Curl:

curl -X PATCH "${BASE_URL}/admin/projects/${PROJECT_ID}/challenges/{challengeId}" \
  -H "Authorization: Bearer ${DEV_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{}'

DELETE /admin/projects/:projectId/challenges/:challengeId

{ "data": { "deleted": true } }

Try it:

curl -X DELETE 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/challenges/%7B%7BchallengeId%7D%7D'

Curl:

curl -X DELETE "${BASE_URL}/admin/projects/${PROJECT_ID}/challenges/{challengeId}" \
  -H "Authorization: Bearer ${DEV_TOKEN}"

GET /admin/projects/:projectId/challenges/:challengeId/participants

Paginated list of participants, ordered by progress DESC.

Query

Response 200

{
  "data": [
    {
      "app_user_id": "…",
      "challenge_id": "…",
      "progress": 5,
      "completed_at": null,
      "app_users": { "display_name": "…", "avatar_url": "…" }
    }
  ],
  "total": 123,
  "offset": 0,
  "limit": 50
}

Try it:

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/challenges/%7B%7BchallengeId%7D%7D/participants'

Curl:

curl -X GET "${BASE_URL}/admin/projects/${PROJECT_ID}/challenges/{challengeId}/participants" \
  -H "Authorization: Bearer ${DEV_TOKEN}"