HTTP API

Achievements

GET/api/v1/achievements

List_achievements

GET
/api/v1/achievements

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Query Parameters

q?string

Full-text search query

page?integer

1-indexed page number

Formatint64
Range0 <= value
page_size?integer

Page size

Formatint64
Range0 <= value
sort_by?string

Sort field

sort_order?string

Sort order (asc or desc)

Value in

  • "asc"
  • "desc"
filter?array<string>

Additional filter expressions in the form field:operator:value

category?string

Filter by category

tier?string

Filter by tier

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"    ]  },  "pagination": {    "has_more": true,    "page": 0,    "page_size": 0,    "total": 0  },  "stats": {    "total_achievements": 0,    "total_possible_points": 0  }}
POST/api/v1/achievements

Define_achievement

POST
/api/v1/achievements

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

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

POST
/api/v1/achievements/events

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

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

POST
/api/v1/achievements/events/batch

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

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

GET
/api/v1/achievements/leaderboards

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Query Parameters

limit?integer

Maximum number of leaderboard entries to return

Formatint64
Range0 <= 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"    }  ],  "user_rank": 0}
GET/api/v1/achievements/users/{user_id}

Get_user_achievements

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

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Path Parameters

user_id*string

User ID

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    }  },  "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

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

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Path Parameters

user_id*string

User ID

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    }  ],  "user_id": "string"}
GET/api/v1/achievements/users/{user_id}/live

Achievement_progress_ws

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

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

GET
/api/v1/achievements/{achievement_id}

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

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

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.

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

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

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.

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

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

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.

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

GET
/api/v1/achievements/{achievement_id}/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  }}

HTTP API

Previous Page

Agent

AI agent identity registry

On this page

List_achievementsDefine_achievementProcess_eventProcess_batch_eventsGet_achievement_leaderboardGet_user_achievementsGet_in_progress_achievementsAchievement_progress_wsGet_achievementDisable_achievementGrant_achievementRevoke_achievementGet_achievement_stats