Achievements

Achievements unlock automatically based on the evaluation of their criteria JSONB. Read the shared CreateAchievementInput type for the full schema.

Most of this surface manages achievement definitions. The two per-user endpoints (/grant, /revoke) are the support / moderation path — manually award or claw back an achievement for a specific user when the automatic criteria evaluation isn't the right tool.

Endpoints

POST /admin/projects/:projectId/achievements

Request

criteria is a JSONB rule tree — see CreateAchievementInput in @layers/amba-shared for the current shape (event-count thresholds, property filters, composite all/any combinators).

Response 201

{
  "data": {
    "id": "…",
    "key": "first_workout",
    "name": "First Workout",
    "xp_reward": 10,
    "criteria": {},
    "is_hidden": false,
    "sort_order": 0
  }
}

Errors

• 500 CREATE_FAILED.

Try it:

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

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/achievements' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET /admin/projects/:projectId/achievements

Ordered by sort_order.

{ "data": [{ "id": "…", "key": "first_workout", "name": "…", "xp_reward": 10 }] }

Try it:

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

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/achievements' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

GET /admin/projects/:projectId/achievements/:achievementId

Errors

• 404 NOT_FOUND.

Try it:

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

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/achievements/{achievementId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

PATCH /admin/projects/:projectId/achievements/:achievementId

Allowed fields: name, description, icon_url, xp_reward, criteria, is_hidden, sort_order, is_active.

Errors

• 404 NOT_FOUND.
• 500 UPDATE_FAILED.

Try it:

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

Curl:

curl -X PATCH '${BASE_URL}/admin/projects/{projectId}/achievements/{achievementId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

DELETE /admin/projects/:projectId/achievements/:achievementId

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

Try it:

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

Curl:

curl -X DELETE '${BASE_URL}/admin/projects/{projectId}/achievements/{achievementId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

POST /admin/projects/:projectId/achievements/:achievementId/grant

Manually unlock an achievement for a specific user (marks it unlocked now). For support, promos, or corrections — the rest of the surface only defines the criteria the system evaluates automatically.

Idempotent: re-granting an already-unlocked achievement keeps the original unlocked_at (no clobber). A grant does not auto-award the achievement's xp_reward — that's reserved for a genuine, criteria-driven unlock. Award XP explicitly via /xp/grant if you want it.

Request (GrantAchievementInput)

Response 201

{
  "data": {
    "app_user_id": "…",
    "achievement_id": "…",
    "unlocked_at": "…"
  }
}

Errors

• 400 VALIDATION_ERROR — app_user_id missing.
• 400 INVALID_ID — achievementId or app_user_id isn't a UUID.
• 404 NOT_FOUND — the achievement definition doesn't exist.
• 500 GRANT_FAILED.

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/achievements/%7B%7BachievementId%7D%7D/grant'

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/achievements/{achievementId}/grant' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "app_user_id": "…" }'

POST /admin/projects/:projectId/achievements/:achievementId/revoke

The inverse of grant: remove a user's unlock entirely.

Request (GrantAchievementInput)

Response 200

{
  "data": {
    "revoked": true,
    "achievement": {
      "app_user_id": "…",
      "achievement_id": "…",
      "unlocked_at": "…"
    }
  }
}

Errors

• 400 VALIDATION_ERROR — app_user_id missing.
• 400 INVALID_ID — achievementId or app_user_id isn't a UUID.
• 404 USER_ACHIEVEMENT_NOT_FOUND — the user doesn't currently hold this achievement.
• 500 REVOKE_FAILED.

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/achievements/%7B%7BachievementId%7D%7D/revoke'

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/achievements/{achievementId}/revoke' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "app_user_id": "…" }'