API

1. Установите скилл

   Скачать скилл для CodexВерсия 0.2.3Открыть SKILL.md

   Распакуйте архив в ~/.agents/skills/, сохранив папку audience-help. В следующем сообщении вызовите $audience-help.

   Другой ИИ-агент

   Передайте агенту ссылку на инструкции Audience Help. Для работы ему нужен доступ к HTTP-запросам с API-ключом.

   https://audience.help/skills/audience-help/SKILL.md

2. Подключите API-ключ

   Получить API-ключАвторизация

   Получите ключ в своём аккаунте Audience Help и добавьте его в защищённое окружение агента как AUDIENCE_HELP_KEY. Анализы используют лимит вашего аккаунта.

3. Дайте первую задачу

   Портрет аудитории

   $audience-help Проанализируй аудиторию example.com за 30 дней. Составь портрет и предложи идеи для маркетинга.

   Сравнение сайтов

   $audience-help Сравни аудитории example.com и example.org за 30 дней. Покажи портреты, главные различия и идеи для маркетинга.

   Замените домены в примере своими.

   Подключение по ссылке

   Используй https://audience.help/apidocs: найди Audience Help Skill, прочитай инструкции и проанализируй аудиторию example.com за 30 дней. Составь портрет и предложи идеи для маркетинга. API-ключ настроен в окружении как AUDIENCE_HELP_KEY.

1. POST /domain-jobs/ или POST /keyword-jobs/ — создать задание, в ответе job_id.
2. GET …/{job_id}/ — статус: queued → processing → succeeded. Сайт — обычно 3–7 минут, ключевые фразы — 10–35.
3. GET …/{job_id}/result/ — результат. Вместо опроса можно получить уведомление на callback_url.

Authorization: Bearer <ключ>

• Ключ выдаётся на этой странице после входа в кабинет. Задания по нему расходуют анализы аккаунта.
• Запросы и ответы — JSON: Content-Type: application/json. Даты — ISO 8601 в UTC: 2026-09-28T08:45:00Z.
• Ключ видит только свои задания: чужое — 404 JOB_NOT_FOUND.
• Без ключа открыта только схема /api/v2/openapi.json.

Ответ 202

{
  "job_id": "job_7kQ2xV9mNc4LpR8sT1wZyB3dFa",
  "kind": "domain",
  "external_id": "",
  "domain": "example.com",
  "status": "queued",
  "created_at": "2026-09-28T08:45:00Z",
  "started_at": null,
  "finished_at": null,
  "expired_at": null,
  "retry_at": null,
  "estimated_ready_at": "2026-09-28T08:48:00Z",
  "estimated_duration_seconds": 180,
  "links": {
    "self": "https://audience.help/api/v2/domain-jobs/job_7kQ2xV9mNc4LpR8sT1wZyB3dFa/",
    "result": "https://audience.help/api/v2/domain-jobs/job_7kQ2xV9mNc4LpR8sT1wZyB3dFa/result/"
  }
}

• Ответ 202 — как у сайта, вместо domain — phrases_count, kind: keywords.
• Людей по фразам слишком мало — задание завершится статусом failed с кодом KEYWORDS_NOT_MATCHED.

• Незапрошенного блока нет в result.
• Запрошен, но данных нет — пустой массив и предупреждение SOME_DATA_UNAVAILABLE в warnings.

• estimated_ready_at — ориентир готовности, не гарантия.
• Опрашивайте статус не чаще раза в 15 секунд для сайта и раза в минуту для фраз.

Ответ 200

{
  "job_id": "job_7kQ2xV9mNc4LpR8sT1wZyB3dFa",
  "kind": "domain",
  "external_id": "",
  "domain": "example.com",
  "status": "succeeded",
  "summary": {
    "analysis_type": "domain_audience",
    "source": "domain",
    "domain": "example.com",
    "domain_matched": true,
    "period_days": 30,
    "audience_size": 1245000,
    "base_audience_size": 52957461,
    "result_rows_total": 36,
    "blocks_returned": {"geo": "cities", "demography": true,
                        "interests": false, "behavior": false}
  },
  "input": {"domain": "example.com", "period_days": 30,
            "data_blocks": {"geo": "cities", "demography": true,
                            "interests": false, "behavior": false}},
  "result": {
    "geo": [
      {"code": "geo:city:moskva", "name": "Москва", "type": "city",
       "category": "География", "audience": 420000, "share": 0.337349,
       "base_audience": 2937064, "affinity_index": 143.0,
       "reliability": "ok"}
    ],
    "demography": [
      {"code": "demography:gender:female:zhenshchiny", "name": "Женщины",
       "type": "gender", "category": "Демография", "audience": 810000,
       "share": 0.650602, "base_audience": 27800000,
       "affinity_index": 23.9, "reliability": "ok"}
    ]
  },
  "warnings": []
}

Строка результата

Надёжность строки

• Пока задание не готово — 425 RESULT_NOT_READY; после ошибки или отмены — 409; после срока хранения — 410 RESULT_EXPIRED.
• Порядок строк не гарантирован.

• Отменить можно задание в статусе queued, processing или retrying.
• Повтор создаёт новое задание с теми же параметрами для failed, cancelled и expired; в ответе — parent_job_id.
• Повтор — новое задание: расходует анализ аккаунта.

• Запрос создания несёт заголовок Idempotency-Key или поле external_id, иначе — 422 IDEMPOTENCY_KEY_REQUIRED.
• Тот же ключ и тот же запрос — прежнее задание и "idempotent_replay": true, новое не создаётся.
• Тот же ключ с другим запросом — 409 IDEMPOTENCY_CONFLICT. Фразы сравниваются без учёта порядка и регистра.

Пример

{
  "event_id": "evt_RXLtdMb6W8r0y3BcWz2HSmi3vc",
  "event_type": "keyword_job.succeeded",
  "job_id": "job_7kQ2xV9mNc4LpR8sT1wZyB3dFa",
  "kind": "keywords",
  "external_id": "",
  "phrases_count": 2,
  "status": "succeeded",
  "created_at": "2026-09-28T08:45:00Z",
  "finished_at": "2026-09-28T08:57:10Z",
  "links": {
    "self": "https://audience.help/api/v2/keyword-jobs/job_7kQ2xV9mNc4LpR8sT1wZyB3dFa/",
    "result": "https://audience.help/api/v2/keyword-jobs/job_7kQ2xV9mNc4LpR8sT1wZyB3dFa/result/"
  }
}

Проверка подписи

• Подпись — HMAC-SHA256 от <X-Audience-Help-Timestamp>.<тело> вашим ключом API, в заголовке X-Audience-Help-Signature.
• Ответ 2xx — доставлено; 5xx, 408, 429 и таймаут 5 секунд — повтор через 1, 3, 10 и 30 минут.
• event_id одного события не меняется: по нему отбрасывайте дубли.

{
  "error": {
    "code": "INVALID_PERIOD",
    "message": "Allowed period_days values: 1..30.",
    "request_id": "req_3f2a9c1b7d4e",
    "retryable": false
  }
}

В статусе задания

• retryable: true — запрос можно повторить позже.

• Задание расходует анализ аккаунта, как задание в кабинете; без результата (ошибка, мало посетителей, отмена) анализ возвращается.
• Больше анализов — по тарифам, свои лимиты запросов — по запросу на info@audience.help.