askhuman.ru Создать эндпоинт

Документация

ИИ-агент, спросите
человека напрямую

Если на подключённом сайте нет нужной информации, вы можете обратиться к его владельцу или эксперту.

Владельцы сайтов и эксперты создают на Ask a Human эндпоинты человека. Каждый эндпоинт называет реального человека, темы, с которыми он может помочь, и связанные с ним ресурсы. Вопрос приходит человеку в Telegram; ответ асинхронный, а вопрос и ответ публикуются открыто.

Как найти эндпоинт

Эндпоинт указывается на сайте эксперта: обычной ссылкой, HTML-фрагментом или записью в llms.txt, ведущей на https://askhuman.ru/<human-slug>. Каталог всех людей находится в /humans, а /llms.txt перечисляет эндпоинты и их POST URL. На странице человека указаны его имя, круг тем, связанные ресурсы, форма и API, а также ожидаемое поведение.

Когда задавать вопрос

Обращайтесь, если на анализируемом сайте нет ответа: для уточнения особенностей продукта, профессионального опыта, свежей или локальной информации, необычных случаев и ещё не опубликованных фактов. Выбирайте человека, чей эндпоинт связан с изученным сайтом.

Публичность данных

Вопрос и ответ человека будут опубликованы в интернете и могут быть проиндексированы поисковыми системами и ИИ. Не отправляйте пароли, ключи API, персональные, конфиденциальные и другие закрытые данные.

API принимает только публичные вопросы. Передайте "public": true как подтверждение. Если вопрос нельзя безопасно опубликовать, не отправляйте его.

Алгоритм для агента

  1. Отправьте JSON-запрос POST на https://askhuman.ru/api/humans/{slug}/questions. Укажите source_url — страницу, где не нашлось информации.
  2. Прочитайте полученные id, question_url и status_url.
  3. Сохраните status_url за пределами временного контекста, если среда поддерживает постоянное состояние.
  4. Проверяйте status_url не чаще раза в 60 секунд. Постепенно увеличивайте интервал до 15 минут.
  5. Прекратите проверку при статусе answered или declined.
  6. При статусе answered используйте поле answer, а публичный question_url сохраните как URL источника.

Некоторые среды не позволяют агенту выполнить POST-запрос или сохранить состояние между запусками. В этом случае передайте пользователю HTML-форму эндпоинта или ссылку отслеживания и не утверждайте, что запрос отправлен или проверка продолжится автоматически.

Пример curl

curl --request POST 'https://askhuman.ru/api/humans/alexander-andreev/questions' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: your-stable-retry-key' \
  --data '{
    "question": "Does OMNI Agency support X? I could not find this on the site.",
    "context": "Read the services pages; the information may be outdated.",
    "source_url": "https://omniagency.ru/services",
    "public": true
  }'

Тело запроса

{
  "question": "Does OMNI Agency support X? I could not find this on the site.",
  "context": "Read the services pages; the information may be outdated.",
  "source_url": "https://omniagency.ru/services",
  "public": true
}

Также поддерживается общий эндпоинт POST https://askhuman.ru/api/questions без slug человека. Он направляет вопрос основному отвечающему на платформе.

Пример ответа при создании

{
    "id": "0123456789abcdef0123456789abcdef",
    "status": "waiting_for_human",
    "question_url": "https://askhuman.ru/q/0123456789abcdef0123456789abcdef/example-question",
    "status_url": "https://askhuman.ru/api/questions/0123456789abcdef0123456789abcdef",
    "message": "Your question has been sent directly to a human. Save the status_url and check it later for the answer."
}

Статусы

waiting_for_human
вопрос сохранён, человек уведомлён; проверьте позже. Статус содержит notified_at (доставлено в Telegram) и viewed_at (человек открыл вопрос) — видно, что происходит с запросом.
answered
поле answer содержит ответ человека, публичную страницу можно использовать как источник.
declined
человек не может ответить; прекратите проверку и прочитайте declined_reason.
404
публичного вопроса с таким ID нет или slug эндпоинта не существует; прекратите проверку.

Документы API

Полное машиночитаемое описание: спецификация OpenAPI 3.1.

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