Health Инструкция по ключу
● Единая точка входа

Один API.
Десять поисковых сервисов.

JyCode API Gateway принимает один запрос, параллельно запускает все подходящие источники, приводит результаты к единому формату и сохраняет исходные ответы при необходимости.

10подключённых провайдеров
21тип обычного поиска
2источника поиска по лицу
1единый формат ответа

Быстрый старт

Минимальный рабочий запрос через HTTPS.

1 · Ключ

Получите клиентский ключ

sudo cat /root/jycode_gateway_client_key.txt

Либо создайте новый ключ и сразу примените его:

sudo /opt/jycode-gateway/.venv/bin/python \
  /opt/jycode-gateway/scripts/create_gateway_key.py \
  --restart
2 · Запрос

Запустите поиск

curl -sS -X POST "https://tulasay.ru/v1/search" \
  -H "X-API-Key: jg_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "8382799213",
    "search_type": "telegram",
    "include_raw": false
  }'

Авторизация и ключи

Каждый защищённый запрос должен содержать клиентский ключ Gateway.

X-API-Key

Основной и самый простой способ.

X-API-Key: jg_ВАШ_КЛЮЧ

Bearer

Альтернативная стандартная схема.

Authorization: Bearer jg_ВАШ_КЛЮЧ

Несколько клиентов

Разные ключи для бота, сайта и приложения.

GATEWAY_API_KEYS=jg_БОТ,jg_САЙТ,jg_APP
Важно. Ключи внешних сервисов никогда не передаются клиенту. Они остаются на сервере в /opt/jycode-gateway/.env. Клиент знает только ключ jg_....

Эндпоинты

Основные маршруты Gateway.

GET
/healthz

Проверка, что процесс работает. Ключ не нужен.

GET
/readyz

Готовность и список загруженных адаптеров. Ключ не нужен.

GET
/v1/types

Список типов поиска и примечания. Нужен ключ.

GET
/v1/providers

Какие провайдеры включены и настроены.

GET
/v1/providers/status

Проверка статуса, лимитов и доступности поддерживаемых upstream-методов.

POST
/v1/detect

Локально определяет тип запроса без платного поиска.

POST
/v1/search

Главный поиск: параллельный вызов подходящих источников.

POST
/v1/face/search

Multipart-загрузка JPG, PNG, WEBP или GIF до 5 МБ.

POST
/v1/bigbase/open-dossier

Открыть досье BigBase по record_id из поисковой выдачи.

POST
/v1/bigbase/random-dossier

Получить случайное тестовое досье с фильтрами пола, года и поисковой строки.

Тело POST /v1/search

ПолеТипПо умолчаниюОписание
querystringобязательноСтрока поиска, от 1 до 500 символов.
search_typeenumautoТип поиска. При auto используется локальный детектор.
providersarray|nullnullОграничить поиск конкретными провайдерами.
pageinteger1Страница для методов, которые поддерживают пагинацию.
include_rawbooleantrueДобавить исходный JSON каждого источника.
bypass_cachebooleanfalseНе использовать кэш и выполнить новый upstream-поиск.

Типы и маршрутизация

При совпадении методов Gateway запускает несколько сервисов одновременно.

search_typeПримерЗапускаемые инструменты
phone79991234567DepSearch · NightSearch phone · Jitler number · RaidFind phone · DeepScan phone
emailuser@example.comDepSearch · NightSearch email · Jitler sherlock · RaidFind email · DeepScan email
fioИванов Иван ИвановичDepSearch · NightSearch fio · RaidFind fio · DeepScan fio
telegram8382799213 / @usernameNightSearch tg · Jitler funstat + sherlock · RaidFind telegram · DeepScan tg
vkhttps://vk.com/usernameDepSearch · NightSearch vk · Jitler vks + sherlock · RaidFind vk · DeepScan vk
nickusernameDepSearch nick · NightSearch nick · Jitler sherlock · RaidFind nick · DeepScan nick
ip8.8.8.8DepSearch · NightSearch ip · RaidFind ip · DeepScan ip
snils123-456-789 01DepSearch · NightSearch snils · DeepScan snils
inn7712345678DepSearch · NightSearch inn · RaidFind inn · DeepScan inn
auto_vehicleA123BC777 / VINDepSearch · NightSearch car · RaidFind auto · DeepScan car
passport4515123456RaidFind passport · DeepScan passport
okok.ru/profile/...NightSearch ok · DeepScan ok
fbfacebook.com/usernameNightSearch fb · DeepScan fb
tiktok@usernameDepSearch tt
addressМосква, Тверская, 10DepSearch addr
sherlockusernameJitler sherlock
funstat8382799213Jitler funstat
card4111111111111111Gloom card · BigBase search
imei123456789012345Gloom imei · BigBase search
bdate1990-01-01Gloom bdate · BigBase search
socialfacebook.com/userGloom social · BigBase search
facephoto.jpgRaidFind face + DeepScan face через отдельный endpoint
Автоопределение. 11 цифр считаются телефоном. Числовые значения длиной 6–10 цифр определяются как Telegram ID; для 10 цифр дополнительно возвращаются кандидаты ИНН и паспорт.

Десять сервисов

Gateway скрывает различия авторизации, форматов и фоновых задач.

D

DepSearch

GET-интеграция. Специализированные префиксы для nick, snils, inn, ip, TikTok и адреса.

телефонФИОVKавтоадрес
N

NightSearch

POST /api/search с собственным search_type. 404 трактуется как корректное «не найдено».

phonetgvkokfb
J

Jitler

Ротация нескольких ключей, создание фоновой задачи и polling результата.

numbersherlockfunstatvks
R

RaidFind

Единый поиск по типам и отдельный multipart-поиск лица. Gateway добавляет обязательный User-Agent.

searchfacestatus
S

DeepScan

Префиксная маршрутизация обычных запросов и отдельный поиск по фотографии.

fast-resultfull-resultface
O

Onux

Универсальный POST /api/search с X-API-Key и отдельной проверкой статуса аккаунта.

phoneemailtgvkcar
G

Gloom

Bearer-авторизация, список ключей, round-robin и переключение при временных ошибках.

cardimeibdatesocialaddress
P

PostAuditory

POST /v1/search с X-API-Key для телефона, Telegram username/ID и VK ID.

phonetelegramvk
B

BigBase

Универсальный поиск, открытие досье по record_id и генерация случайного тестового досье.

searchopen_dossierrandom_dossier
E

Epic Search

Bearer REST API для поиска по email, телефону, username, IP, адресу, паспорту, ФИО и авто.

mailphoneusernameipfioauto

Оркестратор

Параллельный запуск, кэш, ограничение одновременности, единые записи и частичный успех.

parallelcachenormalize

Формат ответа

Нормализованные записи и подробный результат каждого инструмента.

{
  "request_id": "uuid",
  "status": "success",
  "query": "8382799213",
  "search_type": "telegram",
  "detected": null,
  "result_count": 3,
  "providers_ok": 5,
  "providers_failed": 0,
  "cached": false,
  "records": [
    {
      "provider": "raidfind",
      "tool": "telegram",
      "title": "Запись",
      "database": "Источник",
      "year": 2025,
      "actuality": 98,
      "fields": {
        "full_name": "Иван Иванов"
      },
      "links": ["https://t.me/username"]
    }
  ],
  "provider_results": [
    {
      "provider": "jitler",
      "tool": "sherlock",
      "ok": true,
      "found": true,
      "status_code": 200,
      "latency_ms": 1530,
      "records": [],
      "raw": {}
    }
  ]
}

Значения status

success — есть результаты, все инструменты ответили.

partial_success — результаты есть, часть инструментов завершилась ошибкой.

not_found — источники ответили, записей нет.

failed — ни один запланированный инструмент не дал успешного ответа.

records и provider_results

records — удобный единый массив для интерфейса.

provider_results — разбор по каждому источнику и инструменту.

raw присутствует только при include_raw=true.

Ошибки

HTTP-ошибки Gateway и ошибки отдельных источников.

КодКогда возникаетЧто делать
400Пустой/неподдерживаемый файл или некорректный запрос.Проверить тело и Content-Type.
401Ключ отсутствует или неверный.Проверить X-API-Key или Bearer.
413Изображение больше установленного лимита.Уменьшить файл до 5 МБ.
422Тело JSON не прошло валидацию.Проверить поля, enum и длины.
429Превышен лимит запросов на ключ.Учитывать Retry-After и повторить позже.
Upstream-ошибки. Обычный поиск чаще возвращает HTTP 200, а ошибка конкретного сервиса находится в provider_results[].error. Поле retryable показывает, имеет ли смысл повторить запрос.

Дополнительные методы BigBase

Методы доступны через защищённые endpoint-ы Gateway.

Открыть досье

curl -sS -X POST "https://tulasay.ru/v1/bigbase/open-dossier" \
  -H "X-API-Key: jg_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"record_id":"RECORD_ID"}'

Случайное тестовое досье

curl -sS -X POST "https://tulasay.ru/v1/bigbase/random-dossier" \
  -H "X-API-Key: jg_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"search":"Москва","sex":"any","year_from":"1980","year_to":"2000"}'

Примеры кода

cURL, Python и JavaScript.

Python · обычный поиск

import httpx

payload = {
    "query": "8382799213",
    "search_type": "telegram",
    "include_raw": False,
}

response = httpx.post(
    "https://tulasay.ru/v1/search",
    headers={"X-API-Key": "jg_ВАШ_КЛЮЧ"},
    json=payload,
    timeout=90,
)
response.raise_for_status()
print(response.json())

JavaScript · автоопределение

const response = await fetch(
  "https://tulasay.ru/v1/detect",
  {
    method: "POST",
    headers: {
      "X-API-Key": "jg_ВАШ_КЛЮЧ",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ query: "8382799213" })
  }
);

const data = await response.json();
console.log(data);

cURL · выбрать провайдеры

curl -sS -X POST "https://tulasay.ru/v1/search" \
  -H "X-API-Key: jg_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "user@example.com",
    "search_type": "email",
    "providers": ["jitler", "deepscan"],
    "include_raw": false,
    "bypass_cache": true
  }'

cURL · поиск по лицу

curl -sS -X POST \
  "https://tulasay.ru/v1/face/search" \
  -H "X-API-Key: jg_ВАШ_КЛЮЧ" \
  -F "image=@photo.jpg"

Тестер запросов

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

Здесь появится ответ сервера.

Эксплуатация

Команды для сервера и важные параметры.

Сервис

sudo systemctl status jycode-gateway
sudo systemctl restart jycode-gateway
sudo journalctl -u jycode-gateway -f

HTTPS

sudo systemctl status caddy
sudo journalctl -u caddy -f
curl https://tulasay.ru/healthz

Конфигурация

sudo nano /opt/jycode-gateway/.env
sudo chmod 600 /opt/jycode-gateway/.env
sudo systemctl restart jycode-gateway

Кэш

По умолчанию повторный одинаковый поиск кэшируется на 180 секунд. Используйте bypass_cache=true только когда требуется новый upstream-запрос.

Rate limit

По умолчанию 30 запросов в минуту на каждый клиентский ключ. Лимит задаётся через RATE_LIMIT_PER_MINUTE.

Конфиденциальность. Поле include_raw=true может вернуть большой объём исходных данных. Для обычного интерфейса и Telegram-бота безопаснее использовать false.