Getting Started
Our API follows REST principles. It provides clear resource-based endpoints, accepts JSON-encoded request bodies, returns responses in JSON format, and relies on standard HTTP methods, authentication mechanisms, and status codes.
You can obtain your personal API key in the BotHub Telegram bot API section.
Base URL
https://api.bothub.center
Authorization
All requests must include the X-API-Key header for authorization:
X-API-Key: 76bcc761e5d6fe711b866d12f4bb4645461f8b0e
Methods
This section describes all available API methods, including their purpose, request parameters, response formats, and usage examples. Each method also specifies its cost in credits.
User Account
API user account information and statistics.
GET /v1/user/me
Accept: application/json X-API-Key: 76bcc761e5d6fe711b866d12f4bb4645461f8b0e
{
"success": true,
"result": {
"user_id": 123456789,
"credits": {
"phone_email": 244,
"other": 385
},
"registered": "2025-12-01T14:00:00Z"
}
}
GET /v1/user/stats
Accept: application/json X-API-Key: 76bcc761e5d6fe711b866d12f4bb4645461f8b0e
{
"success": true,
"result": {
"methods": {
"search/phone": {
"requests": 10,
"credits": 10
},
"search/email": {
"requests": 5,
"credits": 5
},
},
"total": {
"requests": 15,
"credits": 15
}
}
}
Data Leak Search
Methods for searching data in known leaks.
Performs a search by the specified data type. Outputs results in the form of a collected person profile.
Request cost: 1 credit
Request parameters:
-
type(required) — search type
Supported search types:phone— search by phone number, e.g. 79012345678, +7-902-345-67-89 or +7 (903) 456-78-90email— search by email, e.g. [email protected]inn— search by INN, e.g. 1234567890snils— search by SNILS, e.g. 123-456-789 00gosnomer— search by license plate, e.g. А123ВЕ77vin— search by VIN, e.g. WVGZZZCAZJC520863
query(required) — search data
GET /v1/search/phone/79123456789
Accept: application/json X-API-Key: 76bcc761e5d6fe711b866d12f4bb4645461f8b0e
{
"success": true,
"cost": 1,
"result": {
"names": [
"Ivanov Ivan Ivanovich",
"Vanya"
],
"vk": [
{
"name": "Ivanov Ivan",
"url": "https://vk.com/id12345678"
}
],
"instagram": [
{
"name": "Ivanov Ivan",
"url": "https://www.instagram.com/example"
}
],
"telegram": {
"id": 123456789,
"username": "@example"
},
"birthdays": [
"1999-01-01"
],
"phones": [
"79012345678",
"79012345679"
],
"emails": [
"[email protected]",
"[email protected]"
],
"passwords": [
"qwerty",
"123456"
],
"addresses": [
"Example addresses",
"Example addresses 2"
],
"banks": [
"Example Bank 1",
"Example Bank 2"
],
"gosnomers": [
"А123ВЕ77"
],
"vins": [
"WVGZZZCAZJC520863"
],
"ips": [
"1.2.3.4"
]
}
}
Performs a search for aggregated data, as well as public and private groups that a Telegram user is a member of.
Request cost: 3 credits
Request parameters:
query(required) — userid or username, e.g. 123456789, @elonmusk or durov
GET /v1/telegram/elonmusk
Accept: application/json X-API-Key: 76bcc761e5d6fe711b866d12f4bb4645461f8b0e
{
"success": true,
"cost": 2,
"result": {
"id": 123456789,
"username": "example",
"username_history": [
"example1",
"example2"
],
"name": "Example Name",
"name_history": [
"Example Name 1",
"Example Name 2"
],
"is_scammer": false,
"public_groups": [
{
"id": 123456789,
"title": "Example Title",
"url": "https://t.me/example",
"role": "user"
},
{
"id": 1234567890,
"title": "Example Title 2",
"url": "https://t.me/example2",
"role": "user"
}
],
"private_groups": [
{
"id": 12345678901,
"title": "Example Title 3",
"url": "https://t.me/joinchat/PDfeV0_VzSHefpj3Xow7nq",
"role": "admin"
},
{
"id": 12345678902,
"title": "Example Title 4",
"url": "https://t.me/+cYBNqFkgh-k6XcWm",
"role": "owner"
}
]
}
}
Performs a search by the specified data type. The search result is a list of identified sensitive data along with the source of the data breach.
Request cost: 1 credit
Request parameters:
-
type(required) — search type
Supported search types:username— search by username, e.g. elonmusk or durovpassword— search by password, e.g. 123456 or qwertyhash— search by sha-256 hash of password, e.g. bc6dd981e998b0c4989bfcad2529fe4c3a56c0fd7d9e5a9e09258b4e179cdb16domain— search by domain name, e.g. gmail.com
query(required) — search data
GET /v1/leaks/username/elonmusk
Accept: application/json X-API-Key: 76bcc761e5d6fe711b866d12f4bb4645461f8b0e
{
"success": true,
"cost": 1,
"result": [
{
"leak_source": {
"name": "Deezer.com",
"date": "2019-09"
},
"leak_data": {
"country": "RU",
"birthday": "1999-01-01",
"username": "example",
"email": "[email protected]"
}
},
{
"leak_source": {
"name": "Forums.LinuxMint.com",
"date": "N/A"
},
"leak_data": {
"password": "qwerty",
"ip": "1.2.3.4",
"username": "example",
"email": "[email protected]"
}
},
{
"leak_source": {
"name": "Forbes.com",
"date": "2014-02"
},
"leak_data": {
"password": "123456",
"name": "Example",
"username": "example",
"email": "[email protected]"
}
}
]
}
Searches known Wi-Fi device databases and provides basic information about the device, its location, as well as the network SSID and password (if available).
Request cost: 1 credit
Request parameters:
query(required) — device MAC address, e.g. 58:8B:F3:2E:E7:DA, AC-84-C6-B4-DF-10 or 78d2.9476.4130
GET /v1/mac/58:8B:F3:2E:E7:DA
Accept: application/json X-API-Key: 76bcc761e5d6fe711b866d12f4bb4645461f8b0e
{
"success": true,
"cost": 1,
"result": {
"mac": "58:8B:F3:2E:E7:DA",
"lat": "0.00000000",
"lon": "0.00000000",
"ssid": "example",
"pass": "qwerty",
"source": "example",
"vendor": "Example"
}
}
Errors
All error responses follow a common format:
{
"success": false,
"error": "Error Message"
}
HTTP Error Codes:
Limits
Access to the API is limited to a rate of 5 RPS per API key. Short-term bursts above this rate may be permitted, as long as the overall average request rate remains within the defined limit.