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

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

Authorization: Bearer aira_live_<43 символа>

Формат ключа — aira_live_ и 43 случайных символа (латиница и цифры, 256 бит энтропии). Ключ показывается один раз при выдаче и хранится у нас только в виде хэша — восстановить его нельзя, только выпустить новый. У организации может быть несколько ключей (ротация: выпустите новый, переключитесь, попросите отозвать старый).

Неверный, отозванный или отсутствующий ключ — всегда один и тот же ответ 401 {"code":"invalid_api_key"}, без уточнений. Приостановленный клиент — 403 {"code":"client_suspended"}.

API рассчитан на вызовы сервер-сервер. CORS не открыт: из браузера обращаться к нему не получится, и не надо — ключ не должен попадать на клиентскую сторону.

Учёт предоплаченный: 1 кредит = 1 аудит. Кредиты начисляет ваш менеджер AIRA.

• Кредит списывается атомарно в момент постановки аудита в очередь (POST /audits → 202).
• Баланс 0 → 402 {"code":"insufficient_credits"}, ничего не создаётся.
• Если аудит завершился ошибкой (failed) — кредит возвращается автоматически, ровно один раз. За наш сбой вы не платите.
• Повторный запуск того же адреса, пока предыдущий аудит ещё не завершён, — 409 {"code":"audit_already_running","auditId":"…"}, без списания.
• Остаток виден в каждом ответе на создание (creditsRemaining) и в GET /account.

queued → running → completed либо failed.

Аудит обычно идёт 1–5 минут. При внутренней повторной попытке статус может временно вернуться из running в queued — это нормально, дождитесь терминального состояния. Отчёт существует только у completed; у failed запрос отчёта отвечает 410 с кодом причины, а кредит уже возвращён.

Рекомендуемый опрос: GET /audits/{auditId} не чаще, чем раз в 15 секунд.

• Общий лимит: 60 запросов в минуту на ключ.
• Создание аудитов: 10 запросов в минуту на ключ (отдельный, более жёсткий лимит на POST /audits).
• Превышение — 429 {"code":"rate_limited"} с заголовком Retry-After (секунды).

Тело: websiteUrl (обязателен), reportLevel — "basic" или "full", не выше уровня вашего договора; без него берётся уровень договора.

curl -X POST https://engine.aisearchtune.com/api/v1/audits \
  -H "Authorization: Bearer aira_live_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"websiteUrl": "https://example.com", "reportLevel": "basic"}'

Ответ 202 Accepted:

{"auditId":"aud_4f1c2b7a9d8e4f0a8c6b5d4e3f2a1b0c","status":"queued","creditsCharged":1,"creditsRemaining":41}

Адрес нормализуется (одна и та же страница в разных написаниях — один сайт); некорректный адрес — 400 {"code":"invalid_url","reason":"…"}. Проверки URL и защита от обращений во внутренние сети — те же, что у сайта aisearchtune.com.

curl https://engine.aisearchtune.com/api/v1/audits/aud_4f1c2b7a9d8e4f0a8c6b5d4e3f2a1b0c \
  -H "Authorization: Bearer aira_live_ВАШ_КЛЮЧ"

Ответ 200 (выполняется; progress присутствует только в running):

{"auditId":"aud_4f1c2b7a9d8e4f0a8c6b5d4e3f2a1b0c","status":"running","progress":45,"createdAt":"2026-08-27T10:15:00+00:00"}

Ответ 200 (завершён):

{"auditId":"aud_4f1c2b7a9d8e4f0a8c6b5d4e3f2a1b0c","status":"completed","createdAt":"2026-08-27T10:15:00+00:00","completedAt":"2026-08-27T10:18:12+00:00"}

Чужой или несуществующий идентификатор — всегда 404 {"code":"not_found"}.

curl https://engine.aisearchtune.com/api/v1/audits/aud_4f1c2b7a9d8e4f0a8c6b5d4e3f2a1b0c/report \
  -H "Authorization: Bearer aira_live_ВАШ_КЛЮЧ"

Ответ 200 — конверт с полным JSON отчёта того уровня, с которым аудит был создан:

{"auditId":"aud_4f1c2b7a9d8e4f0a8c6b5d4e3f2a1b0c","websiteUrl":"https://example.com/","reportLevel":"basic","completedAt":"2026-08-27T10:18:12+00:00","report":{ …отчёт… }}

Аудит ещё не завершён — 409 {"code":"audit_not_completed"}. Аудит провалился — 410 {"code":"audit_failed","failureCode":"…"} (кредит уже возвращён).

Параметры: limit (1–100, по умолчанию 20), offset (по умолчанию 0). Сортировка — новые первыми.

curl "https://engine.aisearchtune.com/api/v1/audits?limit=20&offset=0" \
  -H "Authorization: Bearer aira_live_ВАШ_КЛЮЧ"

Ответ 200 (score присутствует только у завершённых):

{"items":[{"auditId":"aud_4f1c2b7a9d8e4f0a8c6b5d4e3f2a1b0c","websiteUrl":"https://example.com/","status":"completed","score":62,"createdAt":"2026-08-27T10:15:00+00:00"}],"total":1,"limit":20,"offset":0}

curl https://engine.aisearchtune.com/api/v1/account \
  -H "Authorization: Bearer aira_live_ВАШ_КЛЮЧ"

Ответ 200:

{"organization":"ООО «Пример»","reportLevel":"full","creditsRemaining":41,"keysActive":2}