Achievements API

POST /v1/achievements/unlock

Unlock an achievement for a player.

Auth: x-game-api-key header

curl -X POST https://api.questdata.io/v1/achievements/unlock \
  -H "Content-Type: application/json" \
  -H "x-game-api-key: YOUR_API_KEY" \
  -d '{
    "achievement_key": "beat_final_boss",
    "player_id": "player-123"
  }'

Request Body

Field	Type	Required	Description
achievement_key	string	Yes	Achievement identifier (defined in dashboard)
player_id	string	Yes	Player identifier

Response (200)

{
  "success": true,
  "achievement": {
    "key": "beat_final_boss",
    "name": "Dragon Slayer",
    "description": "Defeat the final boss",
    "points": 100
  },
  "already_unlocked": false,
  "total_points": 350
}

If the achievement was already unlocked, already_unlocked is true and success is still true.

Error Responses

Status	Body	Cause
400	{ "error": "..." }	Missing required fields
404	{ "error": "Achievement not found" }	Invalid achievement_key

---

GET /v1/achievements

Fetch all achievements with optional player unlock status.

Auth: x-game-api-key header

curl "https://api.questdata.io/v1/achievements?player_id=player-123" \
  -H "x-game-api-key: YOUR_API_KEY"

Query Parameters

Parameter	Type	Description
player_id	string	If provided, includes unlock status per achievement

Response (200)

{
  "achievements": [
    {
      "key": "beat_final_boss",
      "name": "Dragon Slayer",
      "description": "Defeat the final boss",
      "icon_url": "",
      "points": 100,
      "hidden": false,
      "unlocked": true,
      "unlocked_at": "2026-04-08T14:30:00Z"
    },
    {
      "key": "secret_room",
      "name": "???",
      "description": "???",
      "icon_url": "",
      "points": 50,
      "hidden": true,
      "unlocked": false,
      "unlocked_at": null
    }
  ],
  "total_points": 500,
  "unlocked_points": 100
}

Hidden achievements show "???" for name and description until unlocked.