20.1.14. REST API Reference

Every user-facing action in the Challenges module is backed by a REST endpoint. These are documented here for integrators who want to drive challenges from automation, external dashboards, or third-party reward platforms.

All endpoints are served under the configured {{SYSTEM.BASE.API.URL}} prefix and require the X-API-Token header unless noted otherwise.

20.1.14.1. Challenges

Method	Path	Purpose
GET	/challenges	List challenges. Query params: search, status (active / closed / inactive), corporation, page, perPage.
GET	/challenges?id=N	Fetch one challenge with full settings.
POST	/challenges	Create. Body / query params: name, metric, scope, scopeid, threshold, comparator, startdate, enddate, rewardpoints, rewardbadgeid, plus optional hcptypefilter, priorperiodstart, priorperiodend, streakthreshold, autoclose, teamid, rulejson.
PUT	/challenges?id=N	Update. Same fields as create.
DELETE	/challenges?id=N	Delete with full cascade (results + ledger + badge grants).
POST	/challenges/clone?id=N	Duplicate as a new inactive challenge.
POST	/challenges/compute?id=N	Rewrite the results snapshot.
POST	/challenges/preview?id=N	Dry-run close. Returns projected winners + points without mutating.
POST	/challenges/close?id=N	Final close: award points, grant badges, evaluate auto-rules, queue notifications.
POST	/challenges/autoclose-run	Cron hook; closes all eligible challenges whose enddate has passed.
GET	/challenges/results?id=N	Leaderboard snapshot rows.
GET	/challenges/results.csv?id=N	CSV download of the leaderboard.

20.1.14.2. Points ledger

Method	Path	Purpose
GET	/challenges/points	Ledger list. Query params: participanttype, participantid, page, perPage. Response includes totalpoints (sum) and totalrows (pagination total).
POST	/challenges/points/spend	Record a redeem / expire / adjust. Query params: participanttype, participantid, points (positive magnitude), reason (1=redeem, 2=expire, 3=adjust), notes.
GET	/challenges/badges-awarded	Badge-grant list with the same filter shape as points. Paginated.

20.1.14.3. Participant profile

Method	Path	Purpose
GET	/challenges/participant	Aggregate for one participant. Query params: participanttype, participantid. Response: balance, earned, spent, badgecount, badges[], activechallenges[], recentactivity[].

20.1.14.4. Teams

Method	Path	Purpose
GET	/challenges/teams	List teams. Optional corporation= filter.
GET	/challenges/teams?id=N	One team with its members array.
POST	/challenges/teams	Create. Fields: name, description, corporation.
PUT	/challenges/teams?id=N	Update.
DELETE	/challenges/teams?id=N	Soft delete (active = 0).

20.1.14.5. Badges

Method	Path	Purpose
GET	/badges	List badges. Query params: search, corporation, includeinactive.
GET	/badges?id=N	One badge.
POST	/badges	Create. Fields: name, description, icon, color, tier, active.
PUT	/badges?id=N	Update.
DELETE	/badges?id=N	Soft delete.
GET	/badges/auto-rules	List badge auto-rules.
POST	/badges/auto-rules	Create rule. Fields: badgeid, rule_type (0-2), threshold.
DELETE	/badges/auto-rules?id=N	Delete a rule (does not revoke granted badges).

20.1.14.6. Error responses

All endpoints return application/json on error with an error string and, where appropriate, a field hint. HTTP status codes follow the usual convention:

• 400 – validation (bad enum, missing required field).

• 403 – role denied (admin required).

• 404 – record not found.

• 409 – conflict (e.g. spend would overdraw the ledger balance).

• 500 – unexpected server error – details in the server log.

20.1.14.7. Example: close a challenge from curl

curl -X POST \
  -H 'X-API-Token: <token>' \
  'https://your-server/challenges/close?id=42'

# {"success":true}

20.1.14.8. Example: paginated ledger for an auditor

curl -H 'X-API-Token: <token>' \
  'https://your-server/challenges/points?participanttype=2&participantid=17&page=1&perPage=100'