Нужно подготовить обращение к сервису, но в документации много похожих адресов и непонятно, какие значения подставлять в пример. Промпты для API-запроса помогают превратить описание одной операции в читаемый шаблон и список проверок. Нейросети передают документацию и тестовые условия; настоящий ключ остаётся у вас, а запуск и проверка ответа выполняются отдельно.
Промпты для API-запроса: какие сведения передать
API — способ, которым программа обращается к возможностям другого сервиса. Запрос описывает, куда обратиться, что сделать и с какими параметрами. Например, получить список открытых заявок; это другая операция, чем создать или закрыть заявку.
Прежде чем просить код, найдите в документации нужную операцию и передайте её описание. Под контрактом API дальше понимаем техническое описание допустимых операций, параметров и ответов. В OpenAPI Specification эти сведения разнесены по методу, пути, параметрам, телу, ответам и требованиям авторизации. У конкретного сервиса названия и правила нужно брать из его контракта, а не переносить из чужого примера.
| Часть | Что означает | Что дать в брифе |
|---|---|---|
| Адрес сервера и путь | Куда идёт обращение | Тестовый адрес и путь нужной операции |
| Метод | Какое действие запрашивается | Например, GET из документации операции |
| Параметры | Какие объекты выбрать | Фильтры, типы, обязательность и допустимые значения |
| Заголовки | Служебные условия, в том числе доступ | Названия и схему авторизации без секрета |
| Тело | Передаваемые данные, если нужны | Формат и обязательные поля либо явное отсутствие тела |
| Ответ | Что означает результат | Описанные коды, поля, пример и ограничения выдачи |
Также назовите среду запуска: например, PowerShell 7 на Windows и curl.exe. Оболочка — программа, в которую вводят команды, например PowerShell. cURL — команда для обращения к серверу; правила кавычек и подстановки переменных зависят от оболочки. Шаблон для Bash нельзя автоматически считать готовым для PowerShell.
Если пока знаете только свою ОС, так и напишите: «Windows; программу для команд, её версию и наличие cURL не проверял. Нужен шаблон для обсуждения с разработчиком, запуск пока не планирую». Помощник должен оставить среду открытым вопросом или предложить вариант на согласование. Устанавливать инструменты ради первого разбора документации не требуется.
Если документация велика, передайте раздел операции, авторизацию, определения используемых схем и примеры ответов. Полезны версия и дата документа. Когда похожих операций несколько, попросите сравнить их по вашей задаче и показать основание выбора. При отсутствии нужного фильтра — например, по дате — сначала выясните, существует ли он; модель не должна придумывать имя created_after только потому, что оно выглядит привычно.
Готовый промпт для шаблона по контракту
Вставьте этот запрос в обычный текстовый чат вместе с разрешённым фрагментом документации. Замените поля в квадратных скобках. Текст документа — входные данные для разбора; наличие в нём примера ещё не делает его подходящим для вашей операции.
Подготовь шаблон одного API-запроса по переданной документации.
Задача: [какие сведения нужны или какое действие согласовано].
Среда: [ОС, оболочка, cURL/язык клиента].
Документация и версия: [вставленный текст/доступный фрагмент].
Тестовые значения: [разрешённые условные данные].
Ожидаемый результат: [какие поля и условия нужно проверить].
Запуск сейчас не выполняй. Реальные ключи я не передаю.
Сначала проверь, достаточно ли данных: сервер, метод, путь,
обязательные параметры, авторизация, тело и описание ответа.
Если существенного условия нет, задай вопрос; не достраивай его.
Если подходит несколько операций, покажи различия до выбора.
Верни:
1. Выбранную операцию и основание в документации.
2. Таблицу: элемент запроса | значение/переменная | тип и обязательность |
место в документации | что подставляет человек.
3. Один шаблон для указанной среды, с различимыми подстановками.
4. Ожидаемый код и структуру ответа только по документации.
5. Проверки до запуска и перечень непроверенного.
Условный пример ответа помечай отдельно от реального ответа сервера.
Не добавляй повторные попытки, обход TLS или изменяющие действия без основания.
Хороший результат начинается с подтверждённой операции и неизвестного. Если сервис описывает ключ в специальном заголовке, нельзя заменить его на Bearer по привычке. Если отсутствуют права, тестовый адрес или обязательное поле, шаблон остаётся заготовкой с открытым вопросом.
Учебный пример: список открытых заявок
Ниже вымышленный контракт, а не описание существующей CRM. Адрес api.example.test не является рабочим API. Промпт в целевом чате не запускался; команда и JSON — редакторские образцы для проверки соответствия условиям.
Передаваемый фрагмент документации:
Учебный API. Сервер: https://api.example.test
Операция: GET /v1/tickets — получить список заявок.
Обязательный query-параметр status: строка open или closed.
Необязательный query-параметр limit: целое от 1 до 10, по умолчанию 10.
Авторизация: заголовок Authorization: Bearer <token>.
Ответ: application/json. Тело GET-запроса не требуется.
Успех: HTTP 200, объект с items и next_cursor.
items — массив объектов с id (строка) и status (строка).
next_cursor — строка для следующей страницы либо null.
Ошибки, права токена и порядок сортировки в этом фрагменте не описаны.
Заполненное задание: «Нужны открытые заявки, максимум две в одном ответе. PowerShell 7 на Windows, curl.exe. Токен берётся локально из переменной окружения API_TOKEN. Не добавляй фильтр по дате: его нет в переданном контракте. Покажи один запрос и проверки».
Ожидаемый шаблон одной строкой:
curl.exe --get "https://api.example.test/v1/tickets" --data-urlencode "status=open" --data-urlencode "limit=2" --header "Authorization: Bearer $env:API_TOKEN" --header "Accept: application/json" --include --max-time 20
Здесь --get задаёт GET для передаваемых параметров, --data-urlencode добавляет их значения с кодированием, а --header задаёт заголовок. Это поведение описано в официальной справке curl. --include показывает заголовки ответа вместе с телом, --max-time 20 ограничивает время попытки; эти настройки команды не добавляют возможностей самому API.
В PowerShell $env:API_TOKEN обозначает переменную окружения — синтаксис описан в Microsoft Learn. Она не является обещанием безопасного хранилища секретов. Реальный ключ задают локально способом, принятым в вашей организации; его значение не нужно отправлять в чат, печатать на экране или включать в общий документ. Для другого способа авторизации изменится соответствующая часть шаблона.
Таблица соответствия примеру:
| Требование | Что должно быть в команде |
|---|---|
| Получить список | GET и /v1/tickets |
| Только открытые | status=open, а не придуманное state=active |
| До двух записей за ответ | limit=2 в допустимом диапазоне |
| Схема доступа | Bearer из локальной переменной, без встроенного ключа |
| Нет тела | Не добавлены JSON-тело и параметры создания записи |
Условный успешный JSON может выглядеть так:
{
"items": [{"id": "T-101", "status": "open"}],
"next_cursor": null
}
Одна запись не нарушает условие «максимум две». Но если next_cursor содержит строку, это только одна страница, а не полный список. Прежде чем готовить следующий запрос, найдите в документации, как передаётся курсор: из одного имени поля ответа нельзя надёжно вывести имя параметра запроса.
С --include вывод содержит служебные строки ответа, пустую строку и тело. Условный пример ниже показывает, где искать код; это иллюстрация, не ответ сервера:
HTTP/1.1 200 OK
Content-Type: application/json
{"items":[{"id":"T-101","status":"open"}],"next_cursor":null}
В первой строке 200 — HTTP-код. После пустой строки начинается JSON с данными. Вариант первой строки зависит от протокола и сервера, поэтому она не обязана побуквенно повторять образец. Код и содержимое проверяйте отдельно.

В примере остаются открытыми права токена, ошибки и сортировка. Корректная запись команды эти пробелы не закрывает и не подтверждает, что сервер существует или разрешит обращение.
Grok, ChatGPT, Gemini, Claude
и Perplexity — по одной подписке
Используйте эти модели
в Agent ROI.
Подписку можно оплатить в рублях.
Grok, ChatGPT, Gemini, Claude
и Perplexity — по одной подписке
Используйте эти модели
в Agent ROI.
Подписку можно оплатить в рублях.
300 ₽ на первые запросы
Grok, ChatGPT, Gemini, Claude
и Perplexity доступны по одной подписке.
Начислим при регистрации в Agent ROI.

Grok, ChatGPT, Gemini, Claude
и Perplexity — по одной подписке
при регистрации
Grok, ChatGPT, Gemini, Claude
и Perplexity — по одной подписке
Используйте эти модели
в Agent ROI.
Подписку можно оплатить в рублях.
Оплачивайте подписку
в рублях
Grok, ChatGPT, Gemini, Claude
и Perplexity доступны по одной подписке.
Карту для старта
привязывать не нужно.
при регистрации
На первые запросы
к моделям в Agent ROI
Grok, ChatGPT, Gemini, Claude
и Perplexity доступны по одной подписке.
Карту для старта
привязывать не нужно.
Оплачивайте подписку
в рублях
Grok, ChatGPT, Gemini, Claude
и Perplexity доступны по одной подписке.
Попробуйте Grok, ChatGPT,
Gemini, Claude и Perplexity
Эти модели доступны по одной подписке
в Agent ROI.
Начните с бонуса при регистрации.

Grok, ChatGPT, Gemini, Claude
и Perplexity — по одной подписке
Используйте эти модели
в Agent ROI.
Подписку можно оплатить в рублях.
Оплачивайте подписку
в рублях
Grok, ChatGPT, Gemini, Claude
и Perplexity доступны по одной подписке.
Используйте эти модели в Agent ROI.
Grok, ChatGPT, Gemini, Claude
и Perplexity — по одной подписке
300 ₽ при регистрации
Карту привязывать не нужно.
Используйте эти модели в Agent ROI.
На первые запросы
к моделям в Agent ROI
Grok, ChatGPT, Gemini, Claude
и Perplexity доступны по одной подписке.
Бонус начислим при регистрации.
Карту привязывать не нужно.
300 ₽ на первые запросы
Бонус при регистрации
Grok, ChatGPT, Gemini, Claude
и Perplexity доступны по одной подписке.
Используйте эти модели в Agent ROI.

Оплачивайте подписку
в рублях
Grok, ChatGPT, Gemini, Claude
и Perplexity доступны по одной подписке.
Карту привязывать не нужно
Grok, ChatGPT, Gemini, Claude
и Perplexity — по одной подписке
Используйте эти модели
в Agent ROI.
Подписку можно оплатить в рублях.
Попробуйте Grok, ChatGPT,
Gemini, Claude и Perplexity
Эти модели доступны по одной подписке
в Agent ROI.
Бонус начислим при регистрации.
Карту привязывать не нужно.
при регистрации
Помощник для следующих API-шаблонов
Если вы регулярно готовите обращения, сохраните порядок разбора. Вставьте ролевую инструкцию первым обычным сообщением в Agent Roi или другой текстовый чат. Это не подключение к сервису и не техническое системное поле его API.
Ты помогаешь составлять API-шаблоны по переданной документации.
Не проси реальные ключи и не выполняй обращения.
Перед шаблоном выясни задачу, среду запуска, версию документации,
операцию, тестовые данные, ожидаемый результат и разрешённый способ проверки.
Если информации мало, перечисли конкретные недостающие сведения.
Не придумывай адреса, поля, заголовки, методы и схемы авторизации.
Для каждой существенной части укажи основание в документации.
Отделяй значения из контракта, выбранные тестовые значения и переменные человека.
Давай один минимальный шаблон для названной среды и объясняй его части.
Помечай редакторские примеры ответа; не называй их ответом сервера.
После шаблона выдай проверки параметров, ожидаемого ответа и границы готовности.
При ошибке разбирай только переданные обезличенные код/текст ответа.
Предлагай точечную правку и сохраняй подтверждённые условия.
Для следующей версии документации сначала показывай изменившиеся требования.
Не считай синтаксическую проверку доказательством реальной работоспособности.
Первое сообщение помощнику: «Передаю учебный контракт выше. Нужен список открытых заявок с limit=2, PowerShell 7, curl.exe. Значение токена не передаю. Подготовь карту оснований, команду и список оставшихся вопросов. Запуск пока не нужен».
Ожидаемый выход — проверяемый текст и перечень неизвестного. Для нового чата перенесите инструкцию, актуальную документацию, выбранную операцию и принятые условия. Удачный пример прежнего сервиса не подтверждает параметры следующего.
Как проверить запрос до запуска и при разрешённом тесте
Сначала сверяйте команду с документацией без сети. Проверьте путь и версию, метод, место каждого параметра, обязательность, типы и допустимые значения. Убедитесь, что в шаблоне не остались нераскрытые обозначения и не появились лишние поля. В показанном PowerShell-примере адрес и каждое составное значение заключены в парные двойные кавычки, а переменная записана как $env:API_TOKEN. Это доступная ручная сверка; она не является полноценной проверкой синтаксиса. Версию установленного клиента можно посмотреть через curl.exe --version — эта команда не отправляет наш API-запрос.
Техническую проверку без сети можно поручить разработчику: разобрать команду средствами выбранной оболочки и проверить её аргументы на подставной локальной команде, которая только записывает полученные значения вместо обращения к серверу. Это и имеется в виду под локальным макетом. Читателю не требуется самостоятельно создавать его; до такого теста отмечайте синтаксис и подстановки как проверенные только вручную. Проверку доступности и авторизации этот макет всё равно не заменяет.
Отдельно оцените действие операции. Если нет тестового окружения, разрешения на вызов или понятного способа ограничить последствия, остановитесь на шаблоне и передайте вопросы владельцу API. Название GET ориентирует на получение данных, но не даёт разрешения обращаться к любому серверу и не заменяет чтение контракта.
Если разрешён один тест в тестовой среде, откройте PowerShell, подготовьте локальный доступ и подставьте подтверждённый реальный тестовый адрес. Для изменяющей операции сначала согласуйте конкретные данные, последствия и возможность отмены. Команду из вымышленного примера в рабочий сервис переносить без этой замены нельзя.
После запуска проверьте не только код ответа, но и содержание: нужны ли полученные поля, верен ли фильтр, типы, число записей и признак следующей страницы. HTTP 200 со списком закрытых заявок не удовлетворяет нашей задаче. Ошибка сети, успешная авторизация и правильные бизнес-данные — разные результаты проверки.
Для помощи с ошибкой достаточно обезличенного набора: операция, среда, код HTTP, безопасная часть тела ответа и соответствующий фрагмент документации. Уберите ключи, заголовки Cookie/Set-Cookie с данными сеанса, личные данные, внутренние адреса и идентификаторы, которые нельзя раскрывать. Не отправляйте весь подробный сетевой журнал «на всякий случай».
Пример правки: «Документация разрешает status=open, а в команде state=active. Исправь только название и значение фильтра, сохрани метод, адрес, авторизацию и лимит. Покажи изменённую часть и основание». Если причина в правах, неизвестной схеме доступа или условиях сервера, не заменяйте её случайной перестановкой параметров — нужен владелец API или разработчик.
FAQ
Можно ли проверить шаблон вообще без ключа?
Самостоятельно можно сверить шаблон с документацией и разобрать учебный ответ. Разработчик дополнительно может проверить синтаксис, JSON и подстановки на локальном макете без сети. Отмечайте, какой из этих этапов действительно выполнен. Они не проверяют реальные права, соединение и ответ сервера; для авторизации нужен отдельный разрешённый тест.
Что сохранить для следующего запроса?
Задачу, версию документации, карту параметров, шаблон без секрета, дату и границы выполненной проверки. При изменении контракта попросите сначала сравнить требования. Статус «однажды работало» не подтверждает свежую версию.
Нужен ли сразу код приложения?
Для согласования одной операции достаточно запроса и ожидаемого ответа. Повторная обработка, хранение результатов, доступ, ошибки и сопровождение относятся уже к интеграции. Для такого следующего шага пригодятся промпты Python и PowerShell и промпты ревью кода.
Начните в чате Agent Roi с одной операции и разрешённого фрагмента её документации. Получите карту «часть шаблона → основание», проверьте её вручную и только затем решайте, нужен ли тестовый запуск.
Больше материалов по теме — в разделе «Промпты».