The miniapps.me API

Tell us what your users do and see their numbers, or ask whether someone upvoted you and reward them in your bot or mini app.

Free, with no plan or billing. 20 requests a second. Stats for your app are free too, and a bot that runs its own code can add its users to the panel.

You ask
curl -G https://miniapps.me/api/v1/upvoted \
  -d app=yourbot \
  -d user=123456789 \
  -H "Authorization: Bearer ma_live_your_key_here"
We answer
{
  "user": 123456789,
  "upvoted": true,
  "since": "2026-05-25",
  "app": "yourbot",
  "icon": "https://miniapps.me/apps/logos/yourbot.jpg",
  "votes": 84
}

How is your app built?

Pick one. Your panel then walks you through it, in at most three steps, with your own bot's details already in the code.

Mini app

Add one line to your mini app's page. You don't need a key.

Set it up or read how it works

Bot with its own code

Create a key, then send us what people do from your code.

Set it up or read how it works

Bot run by the panel

It has no code of its own, so there's nothing to install.

Set it up or read how it works

How it fits your app

The call to our API is the same either way. What changes is where you get the user's id, and where your key is kept. Pick what you are building.

Telegram bot

  1. UserChats with your bot
  2. Your botOn your server. The key stays here.
  3. miniapps.meKnows who upvoted
Show code in
  1. Get the user's id from the update

    Every message Telegram sends your bot says who sent it. In the raw update that is message.from.id. It comes straight from Telegram, so you can trust it.

    bot.py, with aiogram
    user_id = message.from_user.id  # 123456789
  2. Ask miniapps.me

    Send that id and your app's identifier, with your key in the Authorization header. Keep the key in an environment variable, not in your code.

    bot.py
    import os, aiohttp
    
    async def check_upvote(user_id):
        async with aiohttp.ClientSession() as session:
            async with session.get(
                "https://miniapps.me/api/v1/upvoted",
                params={"app": "yourbot", "user": user_id},
                headers={"Authorization": f"Bearer {os.environ['MINIAPPS_KEY']}"},
            ) as res:
                res.raise_for_status()
                return await res.json()
  3. Reply, or unlock something

    If upvoted is true, give them the feature. If it is false, the reply includes a vote_url. Send it as a button with their id on the end, ?r=123456789.

    bot.py
    from aiogram import F, Router
    from aiogram.filters import Command, CommandStart
    from aiogram.types import InlineKeyboardButton, InlineKeyboardMarkup, Message
    
    router = Router()
    
    @router.message(Command("pro"))
    async def pro(message: Message):
        user_id = message.from_user.id
        data = await check_upvote(user_id)
    
        if data["upvoted"]:
            await message.answer("Pro filters are on. Thanks for the upvote!")
            return
    
        button = InlineKeyboardButton(
            text="Upvote on miniapps.me",
            url=f"{data['vote_url']}?r={user_id}",
        )
        await message.answer(
            "Upvote us once to unlock pro filters.",
            reply_markup=InlineKeyboardMarkup(inline_keyboard=[[button]]),
        )
  4. Welcome them back

    They tap the button, upvote, and Telegram brings them back to your chat as /start v_123456789. Run the same check again. Use the id from the update rather than the one in the link, because anyone can type a link.

    bot.py
    # Put this line straight above "async def pro" in step 3,
    # and register the router before your normal /start handler.
    @router.message(CommandStart(deep_link=True, magic=F.args.startswith("v_")))

Count your users too

While you are in that handler, tell us who used the bot. You get a free dashboard with users, active users, commands and languages. We can't check what your server sends, so these numbers are labelled as reported. How stats work, including how a bot with no code of its own gets verified numbers.

bot.py
AUTH = {"Authorization": f"Bearer {os.environ['MINIAPPS_KEY']}"}

async def report(user_id, command):
    event = {"app": "yourbot", "user": user_id,
             "event": "command", "name": command}
    async with aiohttp.ClientSession() as session:
        await session.post("https://miniapps.me/api/v1/events",
                           json=event, headers=AUTH)

await report(message.from_user.id, "/pro")

What to do with the answer

Pro filters are on. Thanks for the upvote!

Unlock a feature

Open a feature, a bonus or a role when upvoted is true. People who already upvoted never see the prompt.

Daily tasks Join the channel Upvote us on miniapps.me

Tick off a task

If your app has quests or daily tasks, make this one of them. Your code checks upvoted, so nobody has to send you a screenshot.

Welcome back. We have 84 upvotes on miniapps.me.

Show your score

Put votes in a welcome message or a stats screen. Use /api/v1/apps if you only need the count.

Get started in three steps

If your app is already listed and verified, you can make your first call in about a minute.

  1. List your app

    Add your app. Once it is live, open it from your profile and paste your bot token to verify it, which proves it is yours. A mini app uses the token of the bot it belongs to.

    Your app's identifier is the last part of its miniapps.me address. For miniapps.me/yourbot, it is yourbot.

    Your apps

    Sign in and your bots appear here with their live upvote counts, which is exactly what the API returns.

  2. Create a key

    Give it a name so you remember what it is for, and tick only what it needs. We show the full key once, so copy it straight away and keep it somewhere private.

    One key works for all your verified apps. If one ever leaks, revoke it and it stops working immediately. To change what a key can do, make a new one and revoke the old one.

    Your keys

    Sign in with Telegram to see your keys and create one.

  3. Make your first call

    Paste this into a terminal with your key in place of the example. Use your own Telegram id for the test.

    If you see JSON with upvoted in it, you are done. If you see error, the error table says what to change.

    Terminal
    curl -G https://miniapps.me/api/v1/upvoted \
      -d app=yourbot \
      -d user=123456789 \
      -H "Authorization: Bearer ma_live_your_key_here"

Reference

Two endpoints for reading, both GET, both answering in JSON. The address is https://miniapps.me. The two that write are under Stats and Add users.

Your key

Send it in the Authorization header on every call. That is the only place we accept it, so it never ends up in a web address or an access log.

Header
Authorization: Bearer ma_live_your_key_here
PermissionWhat it opens
ReadGET /api/v1/upvoted and GET /api/v1/apps
Send statsPOST /api/v1/events
Add usersPOST /api/v1/panel/users

You choose these when you make the key, and they cannot be changed afterwards. A key that writes does not read unless you tick Read as well. Calling something the key has no permission for gets a 403 with the error missing_permission.

GET/api/v1/upvoted

Whether a Telegram user has upvoted your app, plus your current count.

ParameterWhat it is
appRequired. Your app's identifier, the last part of its miniapps.me address.
userRequired. A Telegram user id. To check several, separate up to 100 with commas.
FieldWhat it is
upvotedtrue or false. It goes back to false if they remove their upvote.
sinceThe date they upvoted, in UTC, or null.
votesYour app's total upvotes.
iconYour logo as a full address, or null if the listing has none.
vote_urlYour upvote link. With one id, only there when upvoted is false. With several ids, always there.
resultsOnly with several ids: user, upvoted and since for each one.
?app=yourbot&user=123456789, when they have upvoted
{
  "user": 123456789,
  "upvoted": true,
  "since": "2026-05-25",
  "app": "yourbot",
  "icon": "https://miniapps.me/apps/logos/yourbot.jpg",
  "votes": 84
}
?app=yourbot&user=123456789, when they have not
{
  "user": 123456789,
  "upvoted": false,
  "since": null,
  "app": "yourbot",
  "icon": "https://miniapps.me/apps/logos/yourbot.jpg",
  "votes": 84,
  "vote_url": "https://miniapps.me/v/yourbot"
}
?app=yourbot&user=123456789,987654321, several at once
{
  "app": "yourbot",
  "icon": "https://miniapps.me/apps/logos/yourbot.jpg",
  "votes": 84,
  "vote_url": "https://miniapps.me/v/yourbot",
  "results": [
    { "user": 123456789, "upvoted": true, "since": "2026-05-25" },
    { "user": 987654321, "upvoted": false, "since": null }
  ]
}

GET/api/v1/apps

Your verified apps and their current upvote counts. It takes no parameters. The list is empty if you have no verified listing yet.

icon is a full address you can use in your own messages, and is null if the listing has no logo.

Response
{
  "apps": [
    {
      "app": "yourbot",
      "name": "Your Bot",
      "icon": "https://miniapps.me/apps/logos/yourbot.jpg",
      "url": "https://miniapps.me/yourbot",
      "votes": 84
    }
  ]
}

If something goes wrong

Every failure has a status code, plus JSON with an error code and a message written for a person.

Example, status 401
{
  "error": "bad_key",
  "message": "That key is not valid, or it was revoked."
}
StatusErrorWhat it means
400no_appYou left out app.
400no_userYou left out user.
400bad_useruser has something in it that is not a number.
400too_manyMore than 100 ids in one request.
401no_keyThe Authorization header is missing.
401bad_keyThe key is wrong, or it was revoked.
403missing_permissionThis key was not given the permission that call needs. The reply names it as needs. Make a new key with it.
403not_yoursThat app is not one of your verified listings. The reply lists the ones that are, as your_apps.
429rate_limitedOver 20 requests a second on this key. Wait a moment and retry.

Limits

The per-second cap is there to stop a broken retry loop, not to meter you. Go over and you get a 429, then you are fine again a second later.

20requests a second, per key
10keys per account
Freeno plan, no billing
Noneno monthly cap

Stats

See how many people use your app, and how often they come back. It's free, and there are three ways to turn it on. Which one fits depends on where your code runs.

A free dashboard

Total users, active users, new users, how many come back, your top commands, languages and where people came from.

Numbers on your public page

Your miniapps.me page shows your total, this month and today, labelled by where they came from. Verified numbers show unless you hide them.

A place in Most active

Most active ranks apps by verified users in the last 30 days. You appear once we have counted 50 users.

A bot connected to the panel Verified

For a bot with no code of its own. Telegram sends the bot's updates straight to us, so there is nothing to add, and the numbers don't depend on anything you tell us.

We read who sent each update, their language, the command word and the start payload. Message text is never stored.

Telegram sends a bot's updates to one place only, so any other code running this bot stops receiving them. If your bot has its own code, use the third way.

  1. Open Add your app, paste its token and tick Manage it in the panel.
  2. In the bot's Settings, choose to let the panel run it. Nothing changes until you do.
  3. Counting starts with the next update. To show the numbers publicly, verify your listing with this same bot's token.

The mini app script Verified

One line in your page. Each time someone opens your mini app, the script sends us the launch data Telegram signed. We check Telegram's signature and take the user from that, never from your page, so it can't be faked by calling us with made-up ids.

It sets no cookies and stores nothing on the phone.

Your page must be verified with the token of the bot this mini app belongs to, because that is how we know which bot's launches to accept. If the same bot is also connected to the panel, one person using both counts once.

In your page's head
<script src="https://miniapps.me/stats.js" data-app="yourbot"></script>

data-app is the last part of your miniapps.me address. No listing yet? Connect the bot in the panel and use bot- and its Telegram id: the API page in the panel has the exact line.

POST/api/v1/events Reported

For a bot that runs its own code. Your server tells us what happened, using a key with the Send stats permission, and only for listings you own and have verified. No listing yet? Pass "bot" with your bot's number in the panel instead of "app".

We can't check what a server tells us. Your dashboard shows these numbers from the first event. They stay off your public page until you choose to show them, where they read "Reported by owner, not checked". They never count for Most active.

You send
curl https://miniapps.me/api/v1/events \
  -H "Authorization: Bearer ma_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"app": "yourbot", "user": 123456789,
       "event": "command", "name": "/start",
       "language": "en", "source": "channel_post"}'
We answer, status 202
{
  "ok": true,
  "accepted": 1,
  "label": "reported"
}
Up to 100 events in one request
{
  "app": "yourbot",
  "events": [
    {"user": 123456789, "event": "command", "name": "/start"},
    {"user": 987654321, "event": "message"}
  ]
}
FieldWhat it is
appThe last part of your miniapps.me address. You can leave it out if your key has only one listing.
userRequired. The Telegram user id. We turn it into a hash before storing anything.
eventcommand, message, callback, open or event. If you leave it out, it is event.
nameRequired for command and event. Up to 64 characters, and up to 100 different names of each kind per app. Never put message text or anything personal here.
languageOptional. The user's language code from Telegram, such as en.
sourceOptional. Where they came from, such as your start payload. It only counts on the first event we see from a person. Letters, digits, _ and -, up to 64.
StatusErrorWhat it means
400bad_eventOne event is wrong, and nothing was saved. message says what, and index says which.
400no_appYou left out app and your key has more than one listing, or none.
400no_eventsevents is empty, or is not a list.
400too_manyMore than 100 events in one request.
400bad_jsonThe body is not a JSON object.
403not_yoursThat app is not one of your verified listings. The reply lists the ones that are.
413too_largeThe request is over 64 KB.
422too_many_namesThis app already has 100 different names of that kind.

Keys and limits work as in the rest of the API, so a bad key gets a 401, a key without Send stats gets a 403, and going over 20 requests a second gets a 429. If you turned counting off for this app, you still get a 202, with accepted at 0. An event is dated when it reaches us, so send them as they happen.

What the numbers mean

Total users is everyone we have seen since you turned stats on, so it starts at zero. Active this month is people seen in the last 30 days, and active today is people seen since midnight UTC. Public numbers refresh about every five minutes.

They are separate from the monthly users figure on your page, which comes from Telegram.

What you owe your users

We store a hash of each user id, never the id, and you never see who is who. You still need to tell your users that you count usage, usually in your own privacy policy. What we collect and for how long.

Add your bot's users

If your bot runs its own code, it keeps its own webhook and we never see who starts it. Your code can tell us instead, so those people are there when you send a broadcast from the bot panel.

POST/api/v1/panel/users

Needs a key with the Add users permission, made by the account that connected the bot.

People you add show as not checked yet, the same as a file upload, until a send or a health check confirms them. Sending someone again never changes their status, so a nightly send of your whole list cannot undo a block we found. Repeating a request changes nothing, so a retry after a timeout is safe.

Anyone on your do not contact list stays on it and is never messaged. excluded tells you how many of the ids you sent are on it.

You send
curl https://miniapps.me/api/v1/panel/users \
  -H "Authorization: Bearer ma_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"bot": 42,
       "users": [{"id": 123456789, "language": "en",
                  "source": "ad-november"},
                 987654321],
       "blocked": [555555555]}'
We answer, status 200
{
  "ok": true,
  "bot": 42,
  "received": 3,
  "added": 2,
  "updated": 0,
  "unchanged": 1,
  "rejected": 0,
  "errors": [],
  "excluded": 0,
  "audience": {"used": 3937, "limit": 20000}
}
FieldWhat it is
botRequired. The bot's number, shown on its settings page in the panel.
usersPeople to add or update. Each one is a Telegram user id, or an object with id and, if you have them, language and source. Someone listed twice counts once.
blockedIds of people who blocked the bot. Your code hears about that from Telegram in a my_chat_member update. An id we do not hold is not stored. Someone in both lists counts as blocked.
languageA language code such as en or pt-br, up to 12 characters.
sourceWhere they came from, up to 32 characters: letters, digits, _, . and -. started, imported and unknown_sender are ours and get rejected.
In the answerWhat it means
receivedHow many entries we could count, after dropping repeats.
added, updated, unchangedWhat happened to the entries we could use. Marking someone blocked counts as updated.
rejected, errorsEntries we could not use, and up to 20 of them with a reason: bad_id, bad_language, bad_source or reserved_source. A bad entry does not stop the good ones, so this can happen with a 200.
audienceHow many people your account holds across all its bots, and its limit. limit is null if there is none.
StatusErrorWhat it means
400bad_jsonThe body is not a JSON object.
400bad_botbot is missing, or is not a positive whole number.
400bad_batchusers or blocked is not a list.
400empty_batchBoth lists are empty.
403missing_permissionThe key does not have Add users.
403suspendedThis account's panel is suspended.
403audience_limitThe new people in this request would take your account over its limit, and nothing in the request was applied. new_ids says how many were new. Updates and blocks for people already here still work on their own.
404bot_not_foundThis key's account has no bot with that number.
413batch_too_largeMore than 1000 ids in one request, counting both lists.
413too_largeThe body is over 256 KB.
429rate_limitedOver 60 requests a minute for this account, however many keys it has, or over 20 a second on this key. Put more users in each request. The per-minute answer has a Retry-After header.

Questions

Why would I ask people to upvote?

Upvotes count toward your place in the ranking on miniapps.me: established apps start from a baseline score we set, and every new upvote adds to it. From time to time we also choose apps to post on our Telegram channel. The people already using your app are the ones most likely to back it, and you can reach them more easily than anyone else can.

Can I reward people for upvoting?

Unlocking something behind an upvote is fine. Paying per upvote is not. We keep the IP address behind every upvote, and farmed upvotes get removed along with the listing that farmed them. Ask, do not buy.

Can I call the API straight from my mini app?

No. Your key would be readable by anyone who opens the mini app. Call it from your server, as shown in the mini app walkthrough.

Why does my listing have to be verified?

A key only answers for listings you own and have verified. Without that, a key would be a way to find out whether a named person upvoted a named bot.

What if someone removes their upvote later?

upvoted goes back to false on your next call. If it matters to you, check again each time rather than saving the answer forever.

What if my key leaks?

Revoke it under Your keys and create a new one. A revoked key stops working on the very next call.