layervai/qurl-mcp

Создаёт до 100 qURL за один запрос. Одновызовная альтернатива перебору create_qurl: экономит сетевые обращения и возвращает единый конверт с результатами по каждому элементу. Используй это только тогда, когда пользователь явно хочет несколько qURL в одном запросе. Никогда не используй для одного URL, одного файла, одного изображения или одного вложения. Не используй этот инструмент для загруженных файлов, вложений-изображений, PDF или содержимого файлов в base64 - вместо него вызывай upload_file_data_qurl (режим HTTP) или upload_file_qurl (режим stdio). Не транзакционный: элементы выполняются успешно или падают независимо друг от друга (смотри счётчики 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/geo/UA/AI-agent и лимитов по времени или сессиям. Когда использовать: когда нужно выпустить свежую защищённую ссылку доступа для одноразового или ограниченного по времени доступа (например, отправить клиенту ссылку на скачивание на 24 часа, закрыть документ за IP-allowlist, выдать подрядчику одноразовые учётные данные). НЕ используйте этот инструмент для изображений, PDF, скриншотов или файловых вложений, загруженных в чат. В режиме HTTP MCP они должны идти через upload_file_data_qurl; в режиме stdio используйте upload_file_qurl. Когда НЕ использовать: используйте mint_link, когда у вас уже есть идентификатор ресурса и нужен только дополнительный токен доступа под ним - create_qurl определяет ресурс по целевому URL и может вернуть существующую группировку ресурсов того же типа. Используйте batch_create_qurls, чтобы создать много за один обмен. Используйте update_qurl, чтобы сменить теги или продлить существующий ресурс без выпуска нового. Если пользователь говорит 'дай мне qURL этого изображения/файла', а контент загружен в чат, это неподходящий инструмент. Поведение: не идемпотентно - два вызова создают два разных qURL-токена, хотя оба могут использовать один и тот же resource_id, если целевой URL группируется с существующим ресурсом того же типа (этот инструмент не показывает заголовок Idempotency-Key нижележащего API). Возвращённый qurl_link показывается ОДИН РАЗ в этом ответе и никогда не восстанавливается через get_qurl или list_qurls; сохраните или передайте его сразу. Возвращённый ресурс находится в статусе active, политика и лимиты на токен применены. Задайте expires_in явно для предсказуемого времени жизни; иначе сервис использует значения по умолчанию. Смотрите expires_at в ответе. max_sessions задаётся для каждого выпущенного qURL, а не для всего ресурса; явно задайте one_time_use: false, когда нужно, чтобы max_sessions: 0 означало неограниченное число посетителей. Возвращает: `{ qurl_id: string (q_…), resource_id: string, qurl_link: string (показывается один раз), branded_domain?: string, qurl_site: string, expires_at:…

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

Продлевает время жизни ссылки qURL, отодвигая срок её истечения на относительный интервал. Принимает отображаемый ID ссылки q_ в качестве resource_id или ID ресурса вместе с qurl_id; ресурсу ровно с одной активной ссылкой qurl_id не нужен (если только у него не больше 100 ссылок, которые перечисляются при чтении). Используется, когда единственное нужное изменение: больше времени до истечения. Вместо этого для установки абсолютного expires_at или изменения метки, политики или сессий ссылки следует использовать update_qurl_token. Когда нужно отрезать доступ, следует использовать revoke_qurl_token или delete_qurl. Ссылки, созданные инструментами загрузки, принадлежат файловому коннектору и не могут быть продлены с этого сервера. Не идемпотентно: вызов дважды с одним и тем же extend_by продлевает ссылку дважды; для случаев, когда повторы не должны удваивать сдвиг, следует использовать update_qurl_token с expires_at. Требует qurl:write и qurl:read: перед обновлением читает ресурс, чтобы проверить ссылку и вернуть её, поэтому каждое продление стоит два вызова API (три, когда чтение не перечисляет ссылку). Ссылка не может жить дольше своего ресурса: если собственный expires_at ресурса наступает раньше, сначала его нужно поднять с помощью update_qurl; тогда результат будет содержать extend_warning. Проблемы с выбором ссылки возвращают результат с ошибкой; отклонённое обновление выбрасывает исключение с его HTTP-статусом и кодом ошибки. Возвращает ресурс (той же формы, что и get_qurl); новый срок истечения продлённой ссылки находится в extended_link_expires_at (и qurls[].expires_at), а не в собственном expires_at ресурса.

Получает отдельный ресурс qURL по ID и возвращает его текущее состояние плюс ограниченную выборку токенов доступа. Используйте его, когда у вас есть конкретный resource ID (публичный ключ, CRID или устаревший r_ ID) или отображаемый ID qURL (префикс q_). ID с префиксом q_ автоматически разрешаются в родительский ресурс. Не используйте его для создания нового qURL для только что загруженного изображения, PDF, скриншота или вложения файла. Для содержимого файлов, загруженных в чат в режиме HTTP MCP, используйте вместо него upload_file_data_qurl. Используйте list_qurls, когда нужно найти qURL по статусу, диапазону дат или поисковому запросу. Используйте resolve_qurl, когда у вас есть токен доступа конечного пользователя (префикс at_) и нужно обменять его на лежащий в основе URL. Если пользователь просит «qURL этого изображения/файла», этот инструмент подходит только тогда, когда вы уже знаете существующий resource_id или qurl_id. qurls[] - неупорядоченная выборка, API ограничивает её 100 строками, и она может отсутствовать при просмотре списка, сбое поиска предпросмотра или у скрытых ресурсов, принадлежащих коннектору; используйте qurl_count, чтобы понять, что строк с токенами может быть больше. Одноразовая ссылка qurl_link, полученная при создании, здесь никогда не возвращается.

Перечисляет ресурсы qURL с постраничной разбивкой и необязательной фильтрацией по статусу, диапазону дат или тексту поиска. Когда использовать: поиск - нахождение qURL по статусу (например, всего, что ещё активно), аудит диапазонов дат или полнотекстовый поиск по описаниям и целевым URL (через параметр q). Фильтры объединяются по И (например, status: 'active' + expires_before: '2026-05-01T00:00:00Z' вернёт активные qURL, срок которых вот-вот истечёт). Когда НЕ использовать: если у вас уже есть конкретный ID ресурса, берите get_qurl - он возвращает ту же структуру по каждому ресурсу дешевле и включает детализацию по токенам qurls[], которую list_qurls опускает. А чтобы реально открыть доступ к целевому URL, используйте resolve_qurl. Поведение: только чтение, идемпотентно. Пустой data[] при meta.has_more: false означает, что ни один ресурс не подошёл под фильтры (это не ошибка). Пагинация основана на курсоре: когда meta.has_more равно true, передайте meta.next_cursor в качестве cursor при следующем вызове, чтобы получить следующую страницу. Размер страницы по умолчанию - 20, настраивается через limit вплоть до 100. По умолчанию возвращаются только active qURL; передайте status: 'revoked', чтобы увидеть только отозванные qURL, или 'active,revoked', чтобы увидеть и те, и другие. Прошедший expires_at ресурса не меняет его статус; истекать могут отдельные токены доступа. status: 'expired' - недопустимый фильтр ресурсов. Сортировка по умолчанию - 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[] означает, что для ресурса нет активных сеансов.

Управление доступом издателя. Настраивает следующую версию политики, отправляет или повторно отправляет приглашение по email, выводит список приглашений или consumer grants, одобряет или отклоняет запрос, одобряет credential с id new или отзывает доступ. Перед решением прочитайте текущую версию; при настройке первой политики на существующем приватном ресурсе используется expected_version 0. Для approve поместите expected_version внутрь approval; ноль допускается только для id new. После неопределённого результата приглашения выведите список приглашений перед повторной попыткой. Доступ только по приглашению не имеет consumer requests. Одобрение контракта требует доверенной квитанции о праве издателя и срока действия, а не неподтверждённого заявления об оплате. Удаление завершается только когда session_cleanup завершён; повторяйте тот же removal/version, пока он в ожидании. Электронная почта доказывает контроль над почтовым ящиком, а не юридическую идентичность. Возвращаются только перечисленные поля; invitation secrets и bearer links никогда не возвращаются.

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

Публикует URL с приватным доступом. Необходимо выбрать keys для одобренных учётных данных, invite_only для приглашений по электронной почте от издателя без запросов на доступ, email_capture для проверенного сбора email с согласия, review для проверенных запросов по email или contract для квитанции о праве от бэкенда издателя. Этот инструмент не проверяет оплату. Для создания необходимо использовать версию 1. Повторный вызов создаёт другой ресурс; после неопределённого результата необходимо использовать get_qurl или list_qurls перед повторной попыткой. Для локальных приложений необходимо использовать qURL CLI. Публичный обмен использует create_qurl.

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

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

Запрашивает временную ссылку доступа qURL для ресурса, идентифицируемого по его CRID. Когда пользователь передаёт CRID ресурса с ведущим маркером $, уберите маркер и используйте этот инструмент. Задайте ttl, чтобы запросить время жизни в синтаксисе Go duration; итоговое значение должно быть положительным целым числом секунд. Служба может скорректировать время жизни. Ссылку создаёт API qURL, и она содержит метаданные о сроке истечения и одноразовом использовании.

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

Обновляет предельный срок истечения, теги, описание, кастомный домен или поведение прокси с host-заголовком у ресурса qURL. extend_by/expires_at здесь сдвигают срок действия самого ресурса, а он не продлевает жизнь отдельной ссылки; чтобы изменить срок действия ссылки, используйте extend_qurl или update_qurl_token. Для обновления срока истечения, тегов и описания принимает публичные ключи ресурсов, CRID, устаревшие идентификаторы r_ и отображаемые идентификаторы q_ (q_ разрешается автоматически); для обновления кастомного домена и preserve_host нужен идентификатор ресурса (публичный ключ, CRID или устаревший идентификатор r_), потому что qURL API теперь отдаёт их через 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: "", чтобы явно очистить эти поля. Когда нужно отозвать ресурс полностью, используйте delete_qurl. Ошибки: некорректный или выходящий за границы extend_by отклоняется на этапе валидации входных данных; если входные данные не проходят проверки схемы (одновременно extend_by + expires_at либо ни одного заданного поля), обработчик возвращает блок содержимого с isError: true. И то, и другое происходит до обращения к API. Остальные ошибки API выбрасываются с code/statusCode от API. Возвращает обновлённый ресурс (той же формы, что и get_qurl).

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