HTTP-API · JSON · REST

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

Запускайте технический аудит, дифф и инструменты движка detail.web программно. Базовый URL — https://api.detailweb.ru. Все ответы — JSON. PRO-функции — по API-ключу (тариф PRO+ и выше).

Документация MCP → OpenAPI (Swagger) →

Аутентификация

API-ключ начинается с dwa_ и создаётся в кабинете (Аккаунт → API-ключи) на тарифе PRO+ и выше. Передавайте его одним из способов:

X-API-Key: dwa_ваш_ключ
# или
Authorization: Bearer dwa_ваш_ключ

Часть эндпоинтов работает без ключа (free-режим с урезанным ответом), ключ лишь расширяет доступ. Эндпоинты с пометкой «PRO+» без валидного ключа вернут урезанный результат или 401. Массовый аудит работает по JWT-сессии кабинета, а не по API-ключу.

Тарифы и кредиты

Тяжёлые операции тратят кредиты, лёгкие инструменты — бесплатны. Кредиты можно докупать (PRO+).

Операция	Стоимость
Аудит одной страницы (single-page)	5 кредитов
Deep-crawl	5 + 2 × страниц
Надбавка PageSpeed Insights	+3 кредита
Надбавка W3C-валидации	+3 кредита
Инструменты (robots / sitemap / jsonld / meta), /checks	бесплатно

Тариф	Кредиты	API
Free	30 кр/мес	без ключа, single-page, базовые проверки
PRO	5 000 кр/мес	кабинет; API-ключ не даёт PRO-фич движка
PRO+	15 000 кр/мес	API + MCP, GEO, deep-crawl, дифф
Business	50 000 кр/мес	API многопоток, bulk-аудит, white-label

Эндпоинты

Метод	Путь	Назначение	Доступ
`POST`	`/audit`	Аудит одного сайтаHealth-score, проблемы по категориям, сигналы. С PRO-ключом — deep-crawl, GEO-блок, 40+ проверок.	опц. ключ (PRO расширяет)
`POST`	`/audit/estimate`	Пред-оценка размера сайтаДешёвая прикидка числа страниц по sitemap и хватит ли кредитов на полный обход. Ничего не списывает.	опц. ключ
`POST`	`/audit/diff`	Дифф измененийЧто изменилось с прошлого снимка того же URL: дельта score/health, какие проверки стали хуже/лучше.	ключ PRO+ (stateful)
`POST`	`/audits/bulk`	Массовый аудитПоставить в очередь аудит списка доменов. Списывает кредиты, учитывает дневной лимит.	JWT кабинета, Business+
`GET`	`/checks`	Реестр проверокКаталог всех проверок движка с разбивкой free / PRO по категориям (list_checks).	без ключа
`GET`	`/checks/{id}`	Объяснение проверкиПочему важна и как исправить одну проверку (explain_issue).	без ключа
`POST`	`/tools/robots`	Валидатор robots.txtРазбор по содержимому: синтаксис, sitemap-директива, блокировка CSS/JS и ИИ-краулеров.	без ключа
`POST`	`/tools/sitemap`	Проверка sitemap.xmlФетч по URL (SSRF-защита): формат, число URL, частые ошибки.	без ключа
`POST`	`/tools/jsonld`	Генератор JSON-LDГотовый блок schema.org из полей (Organization, Article, Product, FAQPage…).	без ключа
`POST`	`/tools/meta`	Генератор meta-тегов<head>-теги (title, description, canonical, Open Graph, Twitter) с проверкой длин.	без ключа

Пример: аудит сайта

Запрос:

curl -X POST https://api.detailweb.ru/audit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dwa_ваш_ключ" \
  -d '{ "url": "https://example.com", "depth": 1, "lang": "ru" }'

Ответ (сокращён):

{
  "url": "https://example.com",
  "score": 32,
  "health": 68,
  "grade": "C",
  "grade_label": "Есть что улучшить",
  "issues": ["Нет HSTS", "Описание короче нормы", "robots.txt блокирует CSS"],
  "plan": "pro",
  "depth_used": 1,
  "checks": [
    { "id": "https", "category": "security", "tier": "free", "status": "pass", "title": "HTTPS / SSL" },
    { "id": "hsts", "category": "security", "tier": "free", "status": "warn", "title": "HSTS" }
  ],
  "summary": { "shown": 75, "passed": 60, "warnings": 10, "critical": 5, "skipped": 0, "pro_hidden": 0 },
  "geo": { "score": 54, "has_llmstxt": false, "ai_crawlers_blocked": [] },
  "signals": { "status_code": 200, "response_time_ms": 240, "has_title": true },
  "audited_at": "2026-06-30T08:00:00Z",
  "render_seconds": 3.1,
  "request_id": "0d6f…"
}

Пример: дифф изменений (PRO+)

curl -X POST https://api.detailweb.ru/audit/diff \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dwa_ваш_ключ" \
  -d '{ "url": "https://example.com", "lang": "ru" }'

Без PRO-ключа поле available вернётся false. Первый снимок — first_run: true (сравнивать не с чем).

Пример: валидация robots.txt (без ключа)

curl -X POST https://api.detailweb.ru/tools/robots \
  -H "Content-Type: application/json" \
  -d '{ "content": "User-agent: *\nDisallow: /admin\nSitemap: https://example.com/sitemap.xml", "lang": "ru" }'

Ошибки и лимиты

Не-200 ответы возвращают JSON вида { "detail", "code", "request_id" }. Сохраняйте request_id для корреляции в логах.

Код	Когда
`401`	Отсутствует или невалидный API-ключ (для PRO-эндпоинтов).
`402 / 403`	Недостаточно кредитов или тариф не даёт доступа к функции.
`429`	Превышен rate-limit (или дневной лимит аудитов).
`503`	Целевой сайт недоступен или превышен timeout.

Полная авто-схема — openapi.json и интерактивный Swagger UI. Запустить аудит из ИИ-агента — см. документацию MCP.