Меню документации

Начало

Основы прокси

API для прокси

Кеш ответов

Litport API

MCP-сервер

Litport API

Litport API даёт интеграции доступ к вашим токенам, пакетам и данным об оплате за ГБ (PPG), а также небольшой набор операций записи: местоположение токена, ротация, новый IP и разрешённые IP пакета.

Базовый URL:

https://litport.net/api/v1

Разделы#

Раздел Префикс Страница документации
Токены /tokens API токенов
Пакеты /packages API пакетов
Оплата за ГБ /pay-per-gb API оплаты за ГБ

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

Создайте API-ключ на странице Настройки. Его полное значение остаётся там доступным после создания или ротации.

export LITPORT_API_KEY='lit_replace_with_your_key'
curl 'https://litport.net/api/v1/tokens' \
  -H "Authorization: Bearer $LITPORT_API_KEY"

Внешние клиенты используют схему Bearer в точном виде. Не передавайте ключ в строке запроса, теле JSON, cookie или логине прокси. Храните его как секрет, ограничьте доступ серверными рабочими нагрузками и смените ключ, если он мог утечь.

Кнопки Запустить на этих страницах документации используют ваш аккаунт Litport, в который вы вошли, и только для GET-запросов. Любая запись требует API-ключа Bearer.

Границы данных для подключения#

Данные для подключения Назначение
Логин и пароль токена прокси Открывают соединения плоскости данных через прокси.
ID токена прокси / ID пакета Выбирает токен или пакет в вызове API; не секрет.
API-ключ пользователя (lit_…) Аутентифицирует запросы плоскости управления аккаунта.

Общие правила API#

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

Идентификаторы. Используйте публичные числовые tokenId и packageId. Выбирайте пул с оплатой за ГБ по его authKey, а разрешённый IP — по самому IP. Ни один эндпоинт не принимает и не возвращает ID базы данных.

Имена. Поля пишутся в camelCase. Новые перечисляемые значения и слаги — в нижнем регистре, kebab-case, например awaiting-payment, more-allowed-ips, package-inactive. Коды ошибок остаются в UPPER_SNAKE. Свободный текст (метки, данные для подключения, названия пулов) не ограничен. Несколько значений сохраняют прежнее написание и не переименованы под это правило: trafficBasis: "customer_chargeable" и timezone: "UTC" в ответе usage, а также значения type/status токена.

Значения. Время указывается в ISO-8601 UTC с окончанием Z. Большие объёмы в байтах — десятичные строки, а не JSON-числа, поэтому клиент никогда не теряет точность.

Формы ответов. Одиночный объект приходит как {"data": {...}}. Эндпоинт, возвращающий список, всегда отвечает {"data": [...], "page": {"nextCursor": ...}}. Списки бывают двух видов:

  • постраничный список (GET /tokens, GET /packages, GET /pay-per-gb/geo) принимает limit и cursor;
  • полный список (GET /pay-per-gb/pools, GET /tokens/{tokenId}/location/options) всегда возвращает все элементы, не принимает limit и cursor и сообщает page.nextCursor: null.

Массив внутри объекта, например buckets в usage, ips в разрешённых IP или tokenIds пакета, — обычное поле, а не список эндпоинта.

Пагинация. limit — от 1 до 100, по умолчанию 50. cursor — это page.nextCursor предыдущего ответа, отправленный обратно без изменений; считайте его непрозрачным. Некорректный limit — это 400 INVALID_LIMIT; некорректный или чужой cursor — 400 INVALID_CURSOR. Запрашивайте page.nextCursor, пока он не станет null.

Ошибки. Каждая ошибка имеет вид {"error": {"code", "message", "requestId", "docsUrl"}}, плюс nextChangeAt, когда действует ожидание. Полную таблицу статусов и отдельный заголовок для каждого кода смотрите в разделе Ошибки API.

Запись. Любая запись требует API-ключа Bearer; сессия документации, в которой вы вошли, может только читать. Если у эндпоинта есть тело, отправляйте JSON. Заголовка предусловия нет: побеждает последняя зафиксированная запись. Любую запись можно безопасно повторять, кроме POST /tokens/{tokenId}/new-ip.

Ограничения частоты запросов#

Действуют два ограничения, оба сообщаются через стандартные заголовки.

  • 120 запросов за 60 секунд на один API-ключ. Превышение — это 429 RATE_LIMITED.
  • 20 записей разрешённых IP за 60 секунд на один пакет (PUT/DELETE /packages/{packageId}/allowed-ips…). Ограничение по ключу проверяется первым; запрос, который его прошёл и при этом является записью разрешённых IP, затем проверяется по ограничению пакета, и в ответе будут заголовки именно этого ограничителя.

Читайте RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset в каждом ответе; отклонённый запрос также содержит Retry-After.

Соглашения#

  • Ответы — JSON.
  • X-Request-ID идентифицирует запрос; указывайте его, когда сообщаете о сбое.
  • Аутентифицированные ответы содержат Cache-Control: private, no-store и Vary: Authorization.
  • В этом API нигде нет ETag и предусловий If-Match.

Машиночитаемый контракт#

Используйте документ OpenAPI 3.1 для всех путей, параметров, тел запросов и схем ответов. Обработайте формат ошибок, прежде чем использовать данные отдельных эндпоинтов.

MarkdownOpenAPI