Achievements

GET/api/v1/achievements

List_achievements

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Conditions as filter[][]=. Conditions on different fields all apply. in (any of) and all (every one of, on fields holding several values) take a comma-separated list (\, for a literal comma). exists takes true or false. Datetimes are RFC 3339, now, or a time before now such as -30m, -6h or -7d.

q?string

Full-text search over this list's searchable fields.

Length1 <= length <= 200

sort?string

Comma-separated sort keys, - for descending, at most 1. Keys: name, points, xp, created_at. Default: -created_at.

limit?integer

Rows per page, 1 to 100 (default 25).

Range1 <= value <= 100

cursor?string

The page.next_cursor of the previous page. Cannot be combined with page.

page?integer

A 1-based page number, for jumping. Cannot be combined with cursor.

Range1 <= value

total?boolean

Set to true to include the number of matching rows in page.total.

include_hidden?boolean

Include hidden achievements

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/achievements"

{  "achievements": [    {      "average_completion_time": 0,      "category": "string",      "completion_rate": 0,      "description": "string",      "difficulty": "string",      "id": "string",      "name": "string",      "points": 0,      "tier": "bronze"    }  ],  "filters": {    "categories": [      "string"    ],    "points_range": {      "max": 0,      "min": 0    },    "tiers": [      "bronze"    ]  },  "page": {    "has_more": true,    "next_cursor": "string",    "page": 0,    "total": 0  },  "stats": {    "total_achievements": 0,    "total_possible_points": 0  }}

POST/api/v1/achievements

Define_achievement

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

category*string

description*string

hidden?boolean

icon_url?string|null

id*string

metadata?unknown

name*string

points*integer

Formatint32

Range0 <= value

prerequisites?array<string>

rewards?null|

rules*||||||

tier*AchievementTier

Value in

"bronze"
"silver"
"gold"
"platinum"
"diamond"

xp?integer

Formatint32

Range0 <= value

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/achievements" \  -H "Content-Type: application/json" \  -d '{    "category": "string",    "description": "string",    "id": "string",    "name": "string",    "points": 0,    "rules": {      "event": "string",      "target": 0,      "type": "counter"    },    "tier": "bronze"  }'

{  "achievement_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "initial_state": "locked"}

POST/api/v1/achievements/events

Process_event

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

dedupe_key?string|null

event_data*unknown

event_type*string

timestamp?|

Formatdate-time

user_id?string|null

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/achievements/events" \  -H "Content-Type: application/json" \  -d '{    "event_data": null,    "event_type": "string"  }'

{  "event_id": "string",  "leaderboard_updated": true,  "processed_achievements": [    {      "achievement_id": "string",      "completed": true,      "new_state": "string",      "points_awarded": 0,      "previous_state": "string",      "progress": {        "current": 0,        "percentage": 0.1,        "target": 0,        "type": "counter",        "window_started_at": "2019-08-24T14:15:22Z"      },      "xp_awarded": 0    }  ],  "unlocked_achievements": [    "string"  ],  "webhooks_triggered": 0}

POST/api/v1/achievements/events/batch

Process_batch_events

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

events*array<>

user_id?string|null

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/achievements/events/batch" \  -H "Content-Type: application/json" \  -d '{    "events": [      {        "event_data": null,        "event_type": "string"      }    ]  }'

{  "event_id": "string",  "leaderboard_updated": true,  "processed_achievements": [    {      "achievement_id": "string",      "completed": true,      "new_state": "string",      "points_awarded": 0,      "previous_state": "string",      "progress": {        "current": 0,        "percentage": 0.1,        "target": 0,        "type": "counter",        "window_started_at": "2019-08-24T14:15:22Z"      },      "xp_awarded": 0    }  ],  "unlocked_achievements": [    "string"  ],  "webhooks_triggered": 0}

GET/api/v1/achievements/leaderboards

Get_achievement_leaderboard

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Query Parameters

limit?integer

Rows per page, 1 to 100 (default 25).

Range1 <= value <= 100

cursor?string

The page.next_cursor of the previous page. Cannot be combined with page.

page?integer

A 1-based page number, for jumping. Cannot be combined with cursor.

Range1 <= value

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/achievements/leaderboards"

{  "category": "string",  "entries": [    {      "achievements_count": 0,      "rank": 0,      "tier_breakdown": {        "property1": 0,        "property2": 0      },      "total_points": 0,      "user_id": "string",      "username": "string"    }  ],  "page": {    "has_more": true,    "next_cursor": "string",    "page": 0,    "total": 0  },  "user_rank": 0}

GET/api/v1/achievements/users/{user_id}

Get_user_achievements

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

user_id*string

User ID

Query Parameters

filter?

sort?string

Comma-separated sort keys, - for descending, at most 1. Keys: points, started_at, completed_at, name. Default: name.

limit?integer

Rows per page, 1 to 100 (default 25).

Range1 <= value <= 100

cursor?string

The page.next_cursor of the previous page. Cannot be combined with page.

page?integer

A 1-based page number, for jumping. Cannot be combined with cursor.

Range1 <= value

total?boolean

Set to true to include the number of matching rows in page.total.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/achievements/users/string"

{  "achievements": [    {      "achievement": {        "category": "string",        "description": "string",        "hidden": true,        "icon_url": "string",        "id": "string",        "name": "string",        "points": 0,        "tier": "bronze",        "xp": 0      },      "completed_at": "2019-08-24T14:15:22Z",      "progress": null,      "started_at": "2019-08-24T14:15:22Z",      "state": "string",      "time_remaining": 0    }  ],  "categories": {    "property1": {      "completed": 0,      "points": 0,      "total": 0    },    "property2": {      "completed": 0,      "points": 0,      "total": 0    }  },  "page": {    "has_more": true,    "next_cursor": "string",    "page": 0,    "total": 0  },  "stats": {    "completed_count": 0,    "completion_percentage": 0.1,    "in_progress_count": 0,    "total_points": 0,    "total_xp": 0  },  "user_id": "string"}

GET/api/v1/achievements/users/{user_id}/in-progress

Get_in_progress_achievements

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

user_id*string

User ID

Query Parameters

filter?

sort?string

Comma-separated sort keys, - for descending, at most 1. Keys: time_remaining, name. Default: name.

limit?integer

Rows per page, 1 to 100 (default 25).

Range1 <= value <= 100

cursor?string

The page.next_cursor of the previous page. Cannot be combined with page.

page?integer

A 1-based page number, for jumping. Cannot be combined with cursor.

Range1 <= value

total?boolean

Set to true to include the number of matching rows in page.total.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/achievements/users/string/in-progress"

{  "achievements": [    {      "id": "string",      "name": "string",      "next_milestone": null,      "progress": {        "current": 0,        "percentage": 0.1,        "target": 0,        "type": "counter",        "window_started_at": "2019-08-24T14:15:22Z"      },      "time_remaining": 0    }  ],  "page": {    "has_more": true,    "next_cursor": "string",    "page": 0,    "total": 0  },  "user_id": "string"}

GET/api/v1/achievements/users/{user_id}/live

Achievement_progress_ws

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

user_id*string

User ID

Response Body

curl -X GET "https://example.com/api/v1/achievements/users/string/live"

Empty

GET/api/v1/achievements/{achievement_id}

Get_achievement

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

achievement_id*string

Achievement ID

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/achievements/string"

{  "category": "string",  "description": "string",  "hidden": true,  "icon_url": "string",  "id": "string",  "name": "string",  "points": 0,  "tier": "bronze",  "xp": 0}

PUT/api/v1/achievements/{achievement_id}/disable

Disable_achievement

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

achievement_id*string

Achievement ID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

hide_from_ui?boolean

reason*string

Response Body

curl -X PUT "https://example.com/api/v1/achievements/string/disable" \  -H "Content-Type: application/json" \  -d '{    "reason": "string"  }'

Empty

POST/api/v1/achievements/{achievement_id}/grant

Grant_achievement

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

achievement_id*string

Achievement ID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

notify?boolean

reason*string

user_ids*array<string>

Response Body

curl -X POST "https://example.com/api/v1/achievements/string/grant" \  -H "Content-Type: application/json" \  -d '{    "reason": "string",    "user_ids": [      "string"    ]  }'

Empty

POST/api/v1/achievements/{achievement_id}/revoke

Revoke_achievement

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

achievement_id*string

Achievement ID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reason*string

remove_points?boolean

user_ids*array<string>

Response Body

curl -X POST "https://example.com/api/v1/achievements/string/revoke" \  -H "Content-Type: application/json" \  -d '{    "reason": "string",    "user_ids": [      "string"    ]  }'

Empty

GET/api/v1/achievements/{achievement_id}/stats

Get_achievement_stats

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

achievement_id*string

Achievement ID

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/achievements/string/stats"

{  "achievement_id": "string",  "progress_distribution": {    "property1": 0,    "property2": 0  },  "stats": {    "completion_rate": 0.1,    "total_created": 0,    "total_granted": 0,    "total_revoked": 0,    "total_users_attempted": 0,    "total_users_completed": 0  }}

Achievements

200application/json

400

503

201application/json

400

403

503

200application/json

400

403

503

200application/json

400

403

503

200application/json

400

503

200application/json

400

403

404

503

200application/json

400

403

404

503

101

403

503

200application/json

404

503

204

403

404

503

204

403

404

503

204

403

404

503

200application/json

404

503

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`