ZOV API v1 · рабочее ядро · JSON · IPv4 / IPv6
Источники: X4B VPN feeds (MIT, © 2024 X4B/Mathew Heard), monosans proxy-list (MIT, © 2022 monosans), Tor Project и RIPE NCC. Автоматических подключений к опубликованным прокси нет.
Создайте ключ в dashboard с правом ip:read. Передавайте его только в заголовке Authorization. Базовый адрес: https://api.zov.lat/v1, либо /v1 на основном сайте.
curl 'https://api.zov.lat/v1/ip/8.8.8.8?fields=ip,asn,tor' \ -H 'Authorization: Bearer YOUR_API_KEY'
fields выбирает поля и вложенные пути; exclude применяется после fields. include=sources,history,abuse включает дополнительные данные с проверкой разрешений. missing=omit|null|include_status управляет неизвестными значениями. sources принимает только зарегистрированные ID: tor,ripe,x4b_vpn4,x4b_vpn6,proxy_http,proxy_socks4,proxy_socks5, не URL.
risk_score: 0–100, оценка риска по наблюдениям, не вероятность. VPN: положительное совпадение с X4B VPN feed (IPv4/IPv6). Proxy: совпадение с опубликованным HTTP/SOCKS feed monosans. Совпадения — сведения источника, не активная проверка ZOV. Tor: true только при свежем положительном совпадении. Во всех списках отсутствие даёт null. GeoIP и ML не подключены.
Квоты ключа: 60 запросов/мин, 10 000/день, 100 000/месяц. Batch: максимум 50 IP, 5 запросов/мин на аккаунт, поэлементные ошибки. Экспорт CSV пока выполняется через dashboard из ограниченных результатов.
Ключ хранится только в состоянии страницы и передаётся в заголовке. На основном сайте можно использовать текущую сессию; на docs.zov.lat нужен API-ключ.
| Endpoint | Разрешение | Описание |
|---|---|---|
| GET /ip/{ip} | ip:read | IP Lookup |
| POST /ip/batch | ip:batch | { ips: ["8.8.8.8", "::1"], fields: ["ip", "tor"] } |
| GET /ip/{ip}/history | ip:history:read | Версии наблюдений |
| GET /asn/{asn} | asn:read | Наблюдаемые адреса ASN |
| GET /abuse/{ip} | abuse:read | Официальные abuse контакты |
| GET /stats/overview | stats:read | Агрегаты |
| GET /stats/timeseries?days=7 | stats:read | Временные ряды |
| GET, POST /allowlist и /denylist | rules:read, allowlist:write, denylist:write | IP/CIDR |
| GET, POST /rules | rules:read/write | name, conditions, action, priority |
| POST /rules/preview | rules:read | Dry-run на последних 1000 наблюдениях |
| GET, POST /events | events:read/write | События пользователя |
| GET, POST /analytics/reports | analytics:reports:read/write | Приватные конфигурации отчётов |
| POST /analytics/reports/{id}/run | analytics:reports:read | Результат и ID запуска |
| GET /status/summary | Публично | Статус компонентов |
| GET /health/ready | Публично | PostgreSQL и Redis |
Список остальных маршрутов — в OpenAPI inventory. Полные request/response схемы и SDK на Rust/Java/Minecraft ещё не добавлены.
Ответ: { data, meta: { request_id, api_version, generated_at, cached } }. Ошибка: { error: { code, message, request_id, details } }. HTTP: 401 — ключ/сессия, 403 — разрешение, 404 — запись, 409 — конфликт, 422 — валидация, 429 — квота, 503 — зависимость недоступна.
Приватные списки, события, отчёты и usage изолированы по аккаунту. IP и история общих публичных источников доступны авторизованным аккаунтам. Политики вычисляются для владельца ключа. При отсутствии совпадения — REVIEW.