Base URL: https://api.black-box.cc/v1
Высокопроизводительный OSINT REST API

Документация BlackBox API

Прямой программный доступ к поисковому ядру BlackBox. Агрегация данных по 20+ миллиардам записей, 50+ источникам РФ и СНГ, цифровым идентификаторам, телеком-операторам и Telegram.

Аутентификация

Каждый запрос к API должен быть авторизован с использованием вашего уникального ключа формата bb_live_....

Ключ можно передавать одним из трёх способов (рекомендуется через заголовок):

Способ Синтаксис / Пример Примечание
HTTP Header X-API-Key: bb_live_3f9a7c... Рекомендуемый безопасный вариант
Bearer Token Authorization: Bearer bb_live_3f9a7c... Стандарт OAuth2 / RFC 6750
Query Param ?token=bb_live_3f9a7c... или ?api_key=... Для быстрых тестов и веб-хуков
Где получить ключ: Сгенерируйте токен в панели управления admin.black-box.cc/apikeys или обратитесь в службу поддержки сервиса.

Лимиты и биллинг

Прозрачные условия тарификации запросов без скрытых списаний.
  • Расход баланса: 1 успешный поисковый запрос списывает ровно 1 кредит с баланса вашего ключа. При ошибках валидации параметры (400/401) баланс не списывается.
  • Ограничение частоты (Rate Limit): 70 запросов в минуту на каждый токен. При превышении возвращается код 429 Too Many Requests.
  • Формат ответа: Все ответы возвращаются в формате JSON с кодировкой UTF-8 и временем выполнения в миллисекундах (execution_time_ms).

Профиль и баланс ключа

Методы для проверки статуса токена, остатка кредитов и привязки к аккаунту.
GET /v1/me
Бесплатный вызов · Баланс не списывается

Возвращает метаданные ключа: имя, текущий баланс, активность и дату создания.

{
  "status": "success",
  "name": "Production Core",
  "balance": 480,
  "is_active": true,
  "created_at": "2026-09-17 14:20:00"
}
GET /v1/balance
Легковесный запрос

Быстрая проверка остатка баланса (удобно для индикаторов в CRM и ботах).

{
  "status": "success",
  "balance": 480
}

Партнерская и реферальная программа

Условия начисления бонусов за привлечение пользователей и создание зеркал сервиса.

Стандартная рефералка (+2)

Каждый пользователь получает личную реферальную ссылку. За каждого нового пользователя, запустившего бота, вам начисляется +2 поисковых запроса.

Партнерский статус (+5)

Подайте заявку на partner.black-box.cc. После подтверждения администратором вы получаете +5 поисковых запросов за каждого реферала и персональный alias ссылки.

Зеркала бота в 1 клик (+5 запросов)

Каждый пользователь может создать собственное зеркало BlackBox через @BotFather в Telegram. За каждое созданное зеркало мгновенно начисляется +5 поисковых запросов (лимит до 5 зеркал в календарный месяц).

Единый шлюз зеркал: Список актуальных официальных зеркал и управление вашими ботами доступно по адресу link.black-box.cc.

Коды ответов и ошибки

API использует стандартные HTTP-коды состояния для индикации результатов запросов.
200 OK
Запрос успешно выполнен, найденные данные возвращены в JSON.
400 Bad Request
Некорректные параметры (запрос короче 3 символов или пустой).
401 Unauthorized
Отсутствует API-токен в заголовке или параметрах.
402 Payment Required
Баланс ключа исчерпан (0 запросов). Требуется пополнение.
403 Forbidden
Указанный API-ключ не существует или деактивирован.
429 Rate Limit
Превышен лимит 70 запросов в минуту. Повторите позже.

Примеры интеграции

Готовые шаблоны кода для быстрого подключения API в ваши сервисы.
import asyncio
import httpx

API_KEY = "bb_live_your_token_here"
BASE_URL = "https://api.black-box.cc/v1"

async def search_person(query: str):
    async with httpx.AsyncClient() as client:
        headers = {"X-API-Key": API_KEY}
        params = {"q": query, "type": "auto"}
        
        response = await client.get(f"{BASE_URL}/search", headers=headers, params=params, timeout=30.0)
        
        if response.status_code == 200:
            result = response.json()
            print(f"[+] Успешно! Найдено баз: {result['stats']['sources_count']}")
            return result
        elif response.status_code == 402:
            print("[-] Недостаточно кредитов на балансе ключа!")
        else:
            print(f"[-] Ошибка HTTP {response.status_code}: {response.text}")

asyncio.run(search_person("+79991234567"))