layervai/qurl-mcp

Создаёт до 100 qURL за один запрос. Однократный вызов вместо циклических вызовов create_qurl - сокращает количество обращений и возвращает единую обёртку с результатами по каждому элементу. Не транзакционно: элементы выполняются успешно или с ошибкой независимо (см. счётчики succeeded/failed и error для каждого элемента). Используйте это, когда нужно выпустить много qURL одновременно (например, для подготовки списка поставщиков, раздачи ссылок общего доступа для каждого клиента). Используйте create_qurl для одного ресурса. Форма ответа: { succeeded: number, failed: number, results: BatchItemResult[], request_id?: string }. Каждый results[i] содержит index (соответствует позиции на входе), success, а также либо qurl_link + resource_id + qurl_site + expires_at (успех), либо error: { code, message } (неудача). Успешные элементы также могут содержать branded_domain для текста привязки на пользовательском домене. Сигнализация частичного сбоя: обработчик устанавливает isError: true в ответе инструмента всякий раз, когда failed > 0, чтобы агенты могли ветвиться без разбора JSON. HTTP-уровень также возвращает 400, когда все элементы завершаются ошибкой - это отображается в той же форме (читайте data.results[*].error). Одноразовые ссылки: как и в create_qurl, каждая qurl_link в ответе показывается ОДИН РАЗ. Не теряйте их.

Создаёт qURL — ссылку с политикой и сроком действия, которая закрывает целевой URL фильтрами по IP, гео, User-Agent и AI-агентам, плюс лимиты по времени или сессиям.Когда использовать: выпуск новой защищённой ссылки для одноразового или временного доступа (например, отправить клиенту ссылку на скачивание на 24 часа, закрыть документ белым списком IP, выдать подрядчику одноразовый доступ).Когда НЕ использовать: используйте mint_link, если у вас уже есть ресурс (r_…) и нужен просто дополнительный токен доступа к нему — create_qurl идентифицирует ресурс по целевому URL и может вернуть существующую группировку ресурсов того же типа. Используйте batch_create_qurls, чтобы создать много ссылок за один вызов. Используйте update_qurl, чтобы перемаркировать или продлить существующий ресурс без выпуска нового.Поведение: не идемпотентно — два вызова создают два разных токена qURL, хотя оба могут иметь один resource_id, если целевой URL группируется с существующим ресурсом того же типа (этот инструмент не раскрывает заголовок Idempotency-Key API). Возвращаемый qurl_link показывается ОДИН раз в этом ответе и никогда не восстанавливается через get_qurl или list_qurls; сразу сохраните или поделитесь им. Возвращаемый ресурс находится в статусе active с применённой политикой и лимитами на токен. Если expires_in не указан, API по умолчанию ставит 24ч — не считайте ссылку вечной. max_sessions действует на каждый выпущенный qURL, а не на весь ресурс; явно укажите one_time_use: false, если нужно, чтобы max_sessions: 0 означал неограниченное количество посетителей.Возвращает: { qurl_id: string (q_…), resource_id: string (r_…), qurl_link: string (показывается один раз), branded_domain?: string, qurl_site: string, expires_at: string (RFC 3339), label?: string, type?: string }. qurl_id — единственный отображаемый ID вида q_…, который агент получает в этом ответе — сохраните его, если планируете последующие вызовы get_qurl/update_qurl/mint_link (они принимают любой префикс). Пример: create_qurl({ target_url: 'https://example.com/private', expires_in: '24h', one_time_use: true,…

Навсегда отзывает qURL — ссылка и все токены доступа к ней немедленно перестают работать. Это действие необратимо. Используйте, когда нужно полностью закрыть доступ (скомпрометированная ссылка, ушедший пользователь, завершение сотрудничества). Используйте update_qurl, если нужно только сократить или продлить срок действия, изменить метки или переименовать — эти операции сохраняют существующие токены доступа. Используйте extend_qurl, если нужно только сдвинуть срок истечения. Идемпотентно: API возвращает 404 при повторном удалении, для никогда не существовавших ID и для ресурсов, принадлежащих другому ключу API (несовпадение владельца сворачивается в 404 на стороне сервера, чтобы скрыть факт существования); этот инструмент проглатывает все три случая. Ориентируйтесь на was_already_revoked, чтобы отличить холостой вызов от успешного отзыва при данном запросе. Если ID пришёл от пользователя и владение имеет значение, сначала вызовите get_qurl — 200 подтверждает владение; выброшенная 404 на этой конечной точке так же неоднозначна. Возвращает подтверждающий payload. По умолчанию ресурс исключён из list_qurls; передайте status: "revoked", чтобы увидеть его.

Продлевает срок действия активного qURL на указанный интервал. Удобная обёртка для самого частого сценария — то же самое, что update_qurl({ resource_id, extend_by }). Используйте, когда нужно только добавить времени. Если ещё надо поменять теги, описание или выставить абсолютное expires_at — используйте update_qurl. Чтобы полностью закрыть доступ — delete_qurl. Принимает как r_, так и q_ идентификаторы (q_ автоматически разрешается в родительский ресурс). Не идемпотентна: два вызова с одинаковым extend_by продлевают срок дважды. Если нужно абсолютное значение, используйте update_qurl с expires_at, чтобы повторные попытки при временных ошибках не удваивали продление. Возвращает обновлённый ресурс с новым expires_at (такой же формат, как в get_qurl).

Извлекает один ресурс qURL по ID и возвращает его текущее состояние и ограниченный предпросмотр токенов доступа. Используйте этот инструмент, когда у вас есть конкретный ID ресурса (префикс r_) или отображаемый ID qURL (префикс q_) — q_ ID автоматически разрешаются в родительский ресурс. Используйте list_qurls вместо этого, когда нужно найти qURL по статусу, диапазону дат или поисковому запросу. Используйте resolve_qurl вместо этого, когда у вас есть токен доступа конечного пользователя (префикс at_) и нужно обменять его на исходный URL. qurls[] — неупорядоченный предпросмотр, ограниченный API до 100 строк, и может быть опущен в списках, при сбое предпросмотра или для скрытых ресурсов, принадлежащих коннектору; используйте qurl_count, чтобы определить, что может существовать больше строк токенов. Одноразовый qurl_link, полученный при создании, никогда здесь не возвращается.

Выводит список qURL ресурсов с пагинацией и опциональной фильтрацией по статусу, диапазону дат или тексту поиска. Когда использовать: поиск - нахождение qURL по статусу (например, всё ещё активные), аудит по диапазонам дат или полнотекстовый поиск по описаниям и целевым URL (через параметр q). Фильтры работают по логике И (например, status: 'active' + expires_before: '2026-05-01T00:00:00Z' вернёт активные qURL, срок действия которых скоро истекает). Когда НЕ использовать: используйте get_qurl вместо этого, если у вас уже есть конкретный идентификатор ресурса - он возвращает ту же структуру ресурса дешевле и включает детализацию qurls[] по токенам, которую list_qurls опускает. Используйте resolve_qurl, чтобы непосредственно открыть доступ к целевому URL. Поведение: только чтение и идемпотентность. Пустой data[] с meta.has_more: false означает, что ни один ресурс не соответствует фильтрам (не ошибка). Пагинация на основе курсора: когда meta.has_more равен true, передайте meta.next_cursor как cursor в следующем вызове, чтобы получить следующую страницу. Размер страницы по умолчанию - 20, настраивается через limit до 100. По умолчанию возвращаются только active qURL; передайте status: 'revoked', чтобы увидеть только отозванные qURL, или 'active,revoked', чтобы увидеть оба. Сортировка по умолчанию - created_at:desc; можно переопределить через sort: 'expires_at:asc' и т.д. Возвращает: { data: QURL[], meta: { has_more: boolean, next_cursor?: string, page_size?: number, request_id?: string } } — каждый элемент data[] имеет ту же стабильную структуру ресурса, что и get_qurl, без детализации по токенам. Пример: list_qurls({ status: "active", sort: "expires_at:asc", limit: 10 }) возвращает 10 активных qURL с наименьшим сроком действия.

Перечисляет активные сеансы доступа для ресурса qURL. Используйте это, чтобы проверить, кто сейчас имеет активный доступ, перед ротацией, отзывом или завершением сеансов. Используйте terminate_qurl_sessions, когда активные сеансы нужно завершить, и используйте get_qurl, когда нужны метаданные токена/ресурса, а не состояние активного сеанса. Поведение: только чтение и идемпотентно. Пустой data[] означает, что для ресурса нет активных сеансов.

Создаёт свежую ссылку доступа для существующего ресурса qURL — та же одноразовая семантика отображения, что и в create_qurl.qurl_link. Используйте этот инструмент, чтобы выдать дополнительные ссылки доступа к ресурсу без создания нового qURL (например, для второго получателя или замены после утери оригинальной). Используйте create_qurl, когда нужен совершенно новый ресурс со своим target_url и политикой. Используйте update_qurl, когда нужно только изменить срок действия, теги или описание существующего ресурса. Принимает идентификаторы как с префиксом r_, так и с q_. Ограничения: expires_in и expires_at взаимоисключают друг друга (обработчик возвращает блок с isError: true до любого вызова API, если заданы оба). Если не указан ни один из параметров срока действия, API по умолчанию устанавливает 24 часа с текущего момента. Результат: новая qurl_link показывается ОДИН раз — ни один последующий вызов её не вернёт. Сохраните qurl_id, если нужно сопоставлять будущие события доступа или обновлять этот конкретный токен.

Обменивает токен доступа qURL (префикс at_, который вы извлекли из qurl_link), чтобы раскрыть исходный URL и получить временное, привязанное к IP разрешение на доступ к сети. Используйте это, когда агенту выдали токен доступа и ему нужно получить защищённый ресурс — после успешного разрешения запросы с access_grant.src_ip разрешены к target_url в течение access_grant.expires_in секунд. Используйте get_qurl, если у вас есть идентификатор ресурса (r_) или отображаемый идентификатор qURL (q_) и нужны детали с административной стороны, а не обмен конечного пользователя. Побочные эффекты: расходует одно использование на токенах one_time_use, уменьшает max_sessions и может вызвать срабатывание политик доступа (чёрные списки IP/geo/UA/AI-агентов). `idempotentHint: false` потому что одноразовые токены расходуются при каждом вызове; для неодноразовых токенов в пределах активного окна доступа повторные вызовы по сути бездействуют, но консервативное указание отражает наихудший вариант поведения.

Отзывает один токен qURL в рамках ресурса, не отзывая весь ресурс. Используйте это, когда один получатель/ссылка должен перестать работать, но соседние qURL на том же resource_id должны оставаться активными. Используйте delete_qurl, если нужно отозвать ресурс и все его токены. Ограничения: требуется родительский resource_id (r_…) и отображаемый ID токена (q_…). Повторный отзыв неактивного токена возвращает ошибку API, а не считается идемпотентным.

Завершает активные сеансы доступа для ресурса qURL. Используйте это после сокращения доступа, смены ссылки или реакции на предполагаемую утечку, когда уже открытые сеансы должны быть немедленно завершены. Передайте session_id, чтобы завершить один активный сеанс; опустите его, чтобы завершить все активные сеансы для ресурса. Сначала используйте list_qurl_sessions, если нужно проверить текущие сеансы перед действием. Побочные эффекты: существующие сеансы доступа закрываются; сами токены qURL не отзываются.

Обновляет срок действия, теги, описание, пользовательский домен или поведение host-header прокси для qURL. Более полная альтернатива extend_qurl — используйте update_qurl, когда нужно что-то большее, чем просто сдвиг относительного времени. Принимает как r_, так и q_ идентификаторы для обновления срока действия, тегов и описания (q_ преобразуется автоматически); обновление пользовательского домена и preserve_host требует ID ресурса r_, потому что API qURL теперь обслуживает их через PATCH /v1/resources/{id}. Ограничения: extend_by и expires_at взаимно исключают друг друга; custom_domain/preserve_host нельзя комбинировать с изменением срока действия в одном вызове; должен быть задан хотя бы один поле для обновления (extend_by, expires_at, tags, description, custom_domain, preserve_host). Очистка полей: передайте description: "", tags: [] или custom_domain: "", чтобы явно очистить эти поля. Используйте extend_qurl, если единственное изменение — это сдвиг относительного времени. Используйте delete_qurl, если нужно полностью отозвать URL. Ошибки: если входные данные не проходят проверку схемы (одновременно указаны extend_by и expires_at, или не задано ни одного поля), обработчик возвращает блок содержимого с isError: true до любого вызова API. Остальные ошибки API выбрасываются с code/statusCode от API. Возвращает обновлённый ресурс (такой же структуры, как get_qurl).

Обновляет один токен qURL в ресурсе: срок действия, метку, политику доступа, максимум сессий или продолжительность сессии. Используйте это, когда нужно изменить конкретный токен q_…, не затрагивая соседние токены или метаданные на уровне ресурса. Для изменений на уровне ресурса (описание, теги, пользовательский домен) используйте update_qurl, а для полной остановки работы токена — revoke_qurl_token. Ограничения: extend_by и expires_at взаимоисключающие; должен быть задан хотя бы один поле для обновления токена. Возвращает обновлённую сводку токена.