StealthSurf VPNStealthSurf VPN

API StealthSurf — авторизация, лимиты, формат запросов

Базовая информация об API: авторизация, лимиты, формат запросов и ответов.

Базовый URL

https://api.stealthsurf.net

Все запросы к API выполняются по HTTPS.

Авторизация

API использует Bearer-токены для авторизации. Передавайте API ключ в заголовке Authorization:

curl -X GET "https://api.stealthsurf.net/configs" \
  -H "Authorization: Bearer stlth_XXXXXXXX_YYYYYYYYYYYYYYYYYYYYYYYY"

Формат API ключа

stlth_0123abcd_0123456789abcdef01234567

Формат фиксирован: ^stlth_([a-f0-9]{8})_([a-f0-9]{24})$. После stlth_ допускаются только шестнадцатеричные символы нижнего регистра.

API-ключ открывает доступ к 138 эндпоинтам. Максимум — 5 API ключей на пользователя.

Rate Limiting

Тип лимитаЗначение
Глобальный лимит60 запросов за 60 секунд
Привязка лимитаПо user_id для авторизованных, по IP для остальных
Специфичные лимитыУказаны для каждого endpoint

Ограничения по эндпоинтам

ЭндпоинтЛимит
POST /configs1 запрос/сек
POST /configs/renewal/:id1 запрос/сек
PATCH /configs/:id/settings1 запрос/сек
PATCH /configs/:id/XrayConfig1 запрос/сек
PATCH /configs/:id/awgConfig1 запрос/сек
POST /configs/:id/awgConfig/generate1 запрос/сек
POST /configs/:id/awgConfig/regenerate1 запрос/сек
PATCH /configs/title/:id1 запрос/сек
PATCH /configs/:id/auto-renewal1 запрос/сек
POST /configs/makeBridge1 запрос/сек
GET /configs/available-servers5 запросов/5 сек
GET /configs/:id/serverStats3 запроса/5 сек
POST /configs/:id/subconfig1 запрос/сек
PATCH /configs/:id/subconfig1 запрос/сек
DELETE /configs/:id/subconfig1 запрос/сек
POST /configs/:id/resetXrayConfig1 запрос/4 сек
GET /configs/:configId/devices60 запросов/мин
POST /configs/:configId/devices1 запрос/сек
PATCH /configs/:configId/devices/:deviceId1 запрос/сек
DELETE /configs/:configId/devices/:deviceId1 запрос/сек
POST /cloud-servers1 запрос/5 сек
POST /cloud-servers/renewal1 запрос/5 сек
POST /cloud-servers/:id/reboot1 запрос/30 сек
GET /cloud-servers/:id/serverStats3 запроса/5 сек
POST /cloud-servers/:server_id/configs1 запрос/сек
PATCH /cloud-servers/:server_id/configs/:id/protocol1 запрос/сек
PATCH /cloud-servers/:server_id/configs/:id/xray1 запрос/сек
PATCH /cloud-servers/:server_id/configs/:id/awg1 запрос/сек
POST /cloud-servers/:server_id/configs/:id/awg/generate1 запрос/сек
POST /cloud-servers/:server_id/configs/:id/awg/regenerate1 запрос/сек
PATCH /cloud-servers/:server_id/configs/:id/title1 запрос/сек
DELETE /cloud-servers/:server_id/configs/:id1 запрос/сек
POST /cloud-servers/:server_id/configs/:id/resetXrayConfig1 запрос/4 сек
GET /cloud-servers/:serverId/configs/:configId/devices60 запросов/мин
POST /cloud-servers/:serverId/configs/:configId/devices1 запрос/сек
PATCH /cloud-servers/:serverId/configs/:configId/devices/:deviceId1 запрос/сек
DELETE /cloud-servers/:serverId/configs/:configId/devices/:deviceId1 запрос/сек
GET /paid-options60 запросов/мин
POST /paid-options1 запрос/сек
GET /paid-options/:id/devices60 запросов/мин
DELETE /paid-options/:id/devices1 запрос/5 сек
DELETE /paid-options/:id/devices/:id20 запросов/мин
GET /paid-options/:id/subscription60 запросов/мин
GET /paid-options/:id/configs60 запросов/мин
PATCH /paid-options/:id/limits1 запрос/5 сек
GET /paid-options/:id/stats/:index3 запроса/5 сек
POST /paid-options/:id/configs1 запрос/сек
PATCH /paid-options/:id/configs/:configId/settings1 запрос/сек
PATCH /paid-options/:id/configs/:configId/xray1 запрос/сек
PATCH /paid-options/:id/configs/:configId/awg1 запрос/сек
POST /paid-options/:id/configs/:configId/awg/generate1 запрос/сек
POST /paid-options/:id/configs/:configId/awg/regenerate1 запрос/сек
POST /paid-options/:id/configs/:configId/resetXrayConfig1 запрос/4 сек
GET /paid-options/:id/configs/:configId/devices60 запросов/мин
POST /paid-options/:id/configs/:configId/devices1 запрос/сек
PATCH /paid-options/:id/configs/:configId/devices/:deviceId1 запрос/сек
DELETE /paid-options/:id/configs/:configId/devices/:deviceId1 запрос/сек
PATCH /paid-options/:id/configs/:configId/title1 запрос/сек
POST /xray/keys1 запрос/сек
PATCH /profile/subscriptionLink2 запроса/мин
PATCH /profile/notification-settings5 запросов/мин
GET /profile/referral/withdraw/sbp-bank-list5 запросов/5 сек
GET /profile/promocodes30 запросов/мин
POST /profile/custom-subscriptions3 запроса/5 сек
PATCH /profile/custom-subscriptions/:id/title5 запросов/1 сек
PUT /profile/custom-subscriptions/:id/items3 запроса/2 сек
POST /profile/custom-subscriptions/:id/reset-key2 запроса/10 сек
POST /profile/custom-subscriptions/:id/share/vk-document2 запроса/10 сек
DELETE /profile/custom-subscriptions/:id3 запроса/2 сек
PATCH /profile/custom-subscriptions/:id/devices/settings3 запроса/1 сек
PATCH /profile/custom-subscriptions/:id/devices/:deviceId/blocked3 запроса/1 сек
PATCH /profile/custom-subscriptions/:id/devices/:deviceId/approval3 запроса/1 сек
DELETE /profile/custom-subscriptions/:id/devices/:deviceId3 запроса/1 сек
DELETE /profile/custom-subscriptions/:id/devices1 запрос/2 сек
GET /profile/custom-subscriptions/:id/encrypted-subscription-link3 запроса/мин
PATCH /profile/custom-subscriptions/:id/xray-template/settings3 запроса/сек
PUT /profile/custom-subscriptions/:id/xray-template3 запроса/сек
DELETE /profile/custom-subscriptions/:id/xray-template3 запроса/2 сек
POST /profile/balance/topup1 запрос/сек
GET /profile/balance/calculate5 запросов/сек
GET /profile/balance/monthly-spend5 запросов/сек
GET /profile/payments-history/:id/receipt60 запросов/мин
PATCH /profile/devices/settings5 запросов/1 сек
PATCH /profile/devices/:id/title5 запросов/1 сек
PATCH /profile/devices/:id/blocked5 запросов/1 сек
PATCH /profile/devices/:id/approval5 запросов/1 сек
DELETE /profile/devices/:id5 запросов/1 сек
DELETE /profile/devices1 запрос/1 сек
PATCH /paid-options/:id/titles/:index5 запросов/2 сек
DELETE /paid-options/:id/titles/:index5 запросов/2 сек
POST /paid-options/:id/configs/:configId/subconfig1 запрос/сек
PATCH /paid-options/:id/configs/:configId/subconfig1 запрос/сек
DELETE /paid-options/:id/configs/:configId/subconfig1 запрос/сек
POST /cloud-servers/:server_id/proxies1 запрос/сек
PATCH /cloud-servers/:server_id/proxies/:proxy_id/protocol1 запрос/сек
PATCH /cloud-servers/:server_id/proxies/:proxy_id/title1 запрос/сек
DELETE /cloud-servers/:server_id/proxies/:proxy_id1 запрос/сек
PATCH /cloud-servers/:id/auto-renewal1 запрос/сек
GET /paid-options/:id/configs/available-servers5 запросов/5 сек
PATCH /paid-options/:id/auto-renewal1 запрос/сек
GET /configs/:id/subconfig/protocols60 запросов/мин
GET /paid-options/:id/locations10 запросов/5 сек
GET /paid-options/:id/configs/:configId/subconfig/protocols60 запросов/мин
PATCH /profile/custom-subscriptions/:id/items/order5 запросов/сек
GET /profile/custom-subscriptions/:id/display/settings60 запросов/мин
PATCH /profile/custom-subscriptions/:id/display/settings3 запроса/сек
PATCH /profile/custom-subscriptions/:id/devices/:deviceId/title3 запроса/сек
GET /profile/custom-subscriptions/:id/routing/configs/:type/:refId60 запросов/мин
PUT /profile/custom-subscriptions/:id/routing/configs/:type/:refId3 запроса/сек
DELETE /profile/custom-subscriptions/:id/routing/configs/:type/:refId3 запроса/2 сек
GET /profile/custom-subscriptions/:id/routing/available-tunnels60 запросов/мин

При превышении лимита API вернёт ошибку 429 Too Many Requests.

Если Redis-хранилище ограничителя недоступно, запрос отклоняется с 503 Service Unavailable.

Заголовки ответа

ЗаголовокОписание
X-RateLimit-LimitМаксимальное количество запросов
X-RateLimit-RemainingОставшееся количество запросов
X-RateLimit-ResetUnix timestamp сброса лимита

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

Успешные ответы возвращаются в JSON-формате:

{
  status: boolean       // true при успехе
  statusCode: number    // HTTP код ответа
  data: any             // Данные ответа
}

Бизнес-ошибки, созданные через errorGenerator(), возвращаются с HTTP-статусом 400 и не содержат statusCode:

{
  status: false
  errorCode: number     // Код ошибки (см. справочник)
  message: string       // Описание ошибки
}

Ошибки API-ключа содержат statusCode и возвращаются с HTTP-статусом 401 или 403. Ошибки валидации, стандартные HTTP-исключения NestJS и 429 Too Many Requests используют стандартный формат NestJS и могут иметь другую структуру.

Несовместимые опции конфигурации

При создании или изменении конфигурации некоторые опции нельзя использовать вместе:

Опция 1Опция 2Результат
use_xhttpdisable_flow_realityBAD_REQUEST
use_grpcuse_xhttpBAD_REQUEST
use_grpcdisable_flow_realityBAD_REQUEST
protocol=vless-2410change_sniBAD_REQUEST
protocol=vless-2410disable_sniBAD_REQUEST
protocol=trojan-2901change_sniBAD_REQUEST
protocol=trojan-2901disable_sniBAD_REQUEST
disable_realitychange_sni (для trojan и trojan-2901)BAD_REQUEST
server_idserver_idsBAD_REQUEST
promocodepayment_method_id + tariff_idBAD_REQUEST
promocodeas_key=trueBAD_REQUEST

Зависимости опций

Некоторые опции требуют активации других:

ОпцияТребование
use_warpuse_extended_settings=true
disable_realityuse_extended_settings=true
change_sniuse_extended_settings=true
enable_family_filteruse_extended_settings=true
block_bittorrentuse_extended_settings=true
pass_all_traffic_through_vpnuse_extended_settings=true
use_xhttpuse_extended_settings=true
use_grpcuse_extended_settings=true
dns_presetuse_extended_settings=true
custom_dns_urldns_preset=custom (только схема https)
grpc_multi_modeuse_grpc=true
pass_all_traffic_through_vpnsmart-локация (иначе BAD_REQUEST)

Примечания

  • Все timestamps в Unix формате (секунды)
  • Все суммы в минимальных единицах валюты (рубли для RUB)
  • server_id и server_ids — взаимоисключающие поля; server_ids принимает до 50 серверов, отсортированных по возрастанию задержки (сначала самые быстрые)
  • randomize_fingerprint — использует рандомизированный uTLS-отпечаток вместо chrome
  • use_loopbacks — переливает трафик в следующую группу балансировщика при полном отказе текущей
  • use_extended_settings доступен только для протоколов vless, trojan, vless-2410, shadowsocks-2022, amnezia-wg-2
  • Значения трафика в GET /traffic возвращаются десятичными строками, а не числами; окно хранения статистики — 180 дней

Эндпоинты недоступные через API ключ

Следующие эндпоинты требуют JWT авторизации и не могут быть вызваны через API ключ:

ЭндпоинтМетодОписание
/profile/transfer/createKeyPOSTСоздание ключа переноса
/profile/transfer/activateKeyPOSTАктивация ключа переноса
/profile/passkeysGETСписок Passkeys
/profile/passkeysPOSTРегистрация Passkey
/profile/passkeys/verifyPOSTПодтверждение Passkey
/profile/passkeys/:idDELETEУдаление Passkey
/profile/otpPOSTГенерация OTP
/profile/signInCodePOSTГенерация кода авторизации
/profile/onboardingPATCHЗавершение онбординга
/profileDELETEУдаление аккаунта
/profile/referral/withdraw/sbpPOSTВывод реферального баланса по СБП
/profile/referral/withdraw/cardPOSTВывод реферального баланса на карту
/profile/telegram/connectionGET, POST, DELETEПривязка Telegram
/profile/share/vk-documentPOSTОтправка подписки документом во VK
/profile/main-subscription/orderGET, PATCHПорядок элементов основной подписки
/profile/encrypted-subscription-linkGETЗашифрованная ссылка подписки
/profile/push/subscribePOST, DELETEПодписка на push-уведомления
/profile/push/vapid-keyGETПубличный VAPID-ключ
/profile/feature-modesPATCHПереключение режимов функций
/profile/vpn-statusGETСтатус VPN-подключения
/auth/*ALLВсе эндпоинты авторизации

Помогла ли вам эта статья?

Отключение Reality

В этой статье мы расскажем, как отключить шифрование (Reality) в вашем конфиге через инструменты Xray.

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

Методы для управления VPN конфигурациями: получение, создание, продление, изменение локации.

Содержание

Базовый URLАвторизацияФормат API ключаRate LimitingОграничения по эндпоинтамЗаголовки ответаФормат ответовНесовместимые опции конфигурацииЗависимости опцийПримечанияЭндпоинты недоступные через API ключ