Basics
- Base address:
https://www.balktalk.net/api/dev/v1 - Every call carries the header
Authorization: Bearer ACCESS_TOKEN. - The request body is JSON (
Content-Type: application/json). - An app always acts on behalf of the member who granted it access. There are no calls without a member.
- The error shape and the limits are on the Limits and errors page.
Addresses
Each address shows its scope. Addresses marked as a write have a stricter limit (10 per minute per member).
Signed-in member
GET /me
The member who granted access to the app. With the profile scope the response also carries the profile field.
Scope: identity
Response · 200
{
"data": {
"id": 48213,
"username": "ana",
"display_name": "Ana",
"avatar_url": "https://load.balktalk.net/media/…/avatar.webp",
"verified": true,
"profile_url": "https://www.balktalk.net/u/ana",
"profile": {
"about": "Kafa, kviz i dobra muzika.",
"age": 34,
"gender": "female",
"country_code": "DE",
"country_name": "Njemačka",
"location": "München",
"website": null,
"joined_at": "2024-03-02T10:15:00+00:00"
}
}
}
Public profile of a member
GET /users/{username}
A profile by username, with the fields visible on a public profile. Returns 404 when the member does not exist or there is a block between them and the signed-in member.
Scope: profile
Response · 200
{
"data": {
"id": 5120,
"username": "bojan",
"display_name": "Bojan",
"avatar_url": "https://www.balktalk.net/app/avatars/neutral.svg",
"verified": false,
"profile_url": "https://www.balktalk.net/u/bojan",
"profile": {
"about": "Šah, planine i stari rok.",
"age": 41,
"gender": "male",
"country_code": "BA",
"country_name": "Bosna i Hercegovina",
"location": "Mostar",
"website": null,
"joined_at": "2023-09-18T08:40:00+00:00"
}
}
}
App leaderboards
GET /boards
The boards you created in the portal. An app only sees its own.
Scope: identity
Response · 200
{
"data": [
{
"key": "glavna",
"name": "Najbolji rezultati",
"order": "desc",
"format": "number"
}
]
}
Top of a leaderboard
GET /boards/{key}/scores
The best limit scores (default 20, at most 50) as the signed-in member sees them, and their own score with its rank. me is null until they have a score.
Scope: identity
Parameters
?limit=20
Response · 200
{
"data": [
{
"rank": 1,
"score": 18450,
"achieved_at": "2026-11-15T19:42:07+00:00",
"user": {
"id": 5120,
"username": "bojan",
"display_name": "Bojan",
"avatar_url": "https://www.balktalk.net/app/avatars/neutral.svg",
"verified": false,
"profile_url": "https://www.balktalk.net/u/bojan"
}
}
],
"me": {
"rank": 7,
"score": 9120,
"achieved_at": "2026-11-14T21:03:55+00:00",
"user": {
"id": 48213,
"username": "ana",
"display_name": "Ana",
"avatar_url": "https://load.balktalk.net/media/…/avatar.webp",
"verified": true,
"profile_url": "https://www.balktalk.net/u/ana"
}
},
"board": {
"key": "glavna",
"name": "Najbolji rezultati",
"order": "desc",
"format": "number"
}
}
Save a score
PUT /boards/{key}/scores/me
A score for the signed-in member. It is kept only if it beats their best; improved tells whether this call set a new best. For a board with the time format send milliseconds.
Scope: scores
Write (stricter limit)
Request body
{
"score": 9120
}
Response · 200
{
"data": {
"rank": 7,
"score": 9120,
"achieved_at": "2026-11-14T21:03:55+00:00",
"user": {
"id": 48213,
"username": "ana",
"display_name": "Ana",
"avatar_url": "https://load.balktalk.net/media/…/avatar.webp",
"verified": true,
"profile_url": "https://www.balktalk.net/u/ana"
}
},
"improved": true
}
Member is using the app
POST /activity
Lasts about two minutes - while the member plays, call it once a minute. Who can see it follows their privacy settings on BalkTalk.
Scope: activity
Write (stricter limit)
Response · 204
No body.
Member stopped using the app
DELETE /activity
Removes the “is playing …” indicator right away.
Scope: activity
Response · 204
No body.