BalkTalk

For developers

API reference

Every address of the public API, with the scope it needs and an example response. The list is built from the code, so it always matches what the server really does.

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.

OpenAPI description (JSON)

Strictly necessary cookies keep the site running. With your consent we also use optional ones (e.g. analytics) - you can change your choice at any time. Cookie Policy

Strictly necessary cookies keep the site running. With your consent we also use optional ones (e.g. analytics) - you can change your choice at any time. Cookie Policy

Strictly necessary

Always active

The site cannot work without them: sign-in, security, language and your choices. No consent needed and never used for tracking.

  • bt_session cookie · 30 days

    Session: keeps you signed in while you use the site.

    BalkTalk

  • XSRF-TOKEN cookie · 30 days

    Protects forms against forged requests (CSRF).

    BalkTalk

  • remember_web_* cookie · 13 months

    "Remember me": keeps you signed in after closing the browser.

    BalkTalk

  • bt_locale cookie · 12 months

    The language you chose.

    BalkTalk

  • bt_2fa_device cookie · 30 days

    Two-step sign-in: this device does not ask for a code for 30 days (when you choose "Remember this device").

    BalkTalk

  • bt_consent cookie · 12 months

    Your cookie choice (so we do not ask again).

    BalkTalk

  • bt-*, bt:* localStorage · until you clear it

    Browser local storage: theme, language, radio station, recent emoji, chat layout, hidden hints.

    BalkTalk

  • bt_invite cookie · 30 days

    Who invited you to BalkTalk (invite link) – so you both get a reward once you become an active member.

    BalkTalk

  • Cloudflare Turnstile service

    Human check on sign-up (challenges.cloudflare.com) - protects the site from fake accounts.

    Cloudflare, Inc. · Privacy policy

Third-party content

When you open it

Videos, music, GIFs, radio and the map come from other companies' servers. When you open them, those servers see your IP address and may set their own cookies.

  • Google Identity Services service

    One-click sign-in with the Google account you use in the browser ("Continue as …", accounts.google.com). Google sees that you visited the site; we get your name and email only when you click "Continue". Google may set the g_state cookie to remember that you closed the prompt.

    Google Ireland Ltd. · Privacy policy

  • YouTube service

    Videos in the blog and chat (youtube-nocookie.com).

    Google Ireland Ltd. · Privacy policy

  • Deezer service

    Song previews and covers on profiles, the Network and in chat.

    Deezer S.A. · Privacy policy

  • KLIPY service

    GIFs in chat and comments.

    KLIPY Inc. · Privacy policy

  • Radio stations service

    Live stream when you start the radio.

    The selected station's server

  • OpenStreetMap service

    Map in the Nearby module (only with separate map consent).

    OpenStreetMap Foundation · Privacy policy

  • OneSignal service

    Push notifications on this device – loaded only after you turn them on in Settings.

    OneSignal, Inc. · Privacy policy

Analytics

Anonymous visit statistics that help us improve the site. Only with your consent.

  • Google Analytics service

    Visit statistics (which pages are opened, where visitors come from, device) - no ads. Loaded only with your consent.

    Google Ireland Ltd. · Privacy policy

  • _ga cookie · 24 months

    Google Analytics: tells visitors apart (random number, no name or email).

    Google Ireland Ltd. · Privacy policy

  • _ga_0QPMP1EXWV cookie · 24 months

    Google Analytics: remembers the current visit.

    Google Ireland Ltd. · Privacy policy