Документация · REST API
REST API
JSON-API поверх HTTPS для всего, что делает приложение vetkit. Запускайте аудиты из CI, блокируйте релизы по оценке или отправляйте SARIF в GitHub code scanning.
Обзор
| Базовый URL | https://api.vetkit.dev/v1 |
|---|---|
| OpenAPI | https://api.vetkit.dev/v1/openapi.json — полный машиночитаемый справочник по всем маршрутам и схемам |
| Формат | Тела запросов и ответов в JSON, временные метки ISO 8601, идентификаторы UUID |
| Ошибки | RFC 9457 application/problem+json |
На этой странице описано самое основное. Сгенерируйте клиент или изучите отдельные схемы в документе OpenAPI; MCP-сервер построен на том же API.
Аутентификация
Создайте ключ в разделе Настройки рабочего пространства → API-ключи (доступно только владельцам и администраторам) и передавайте его как Bearer-токен. Ключ принадлежит одной организации и имеет явно заданные области доступа: repos:read, repos:write, audits:read, audits:write, audits:run, findings:read, findings:write, findings:ai-fix, reports:read и agent:check.
curl https://api.vetkit.dev/v1/me \ -H "Authorization: Bearer $VETKIT_API_KEY"В ответе перечислены области доступа ключа, а в organizations — организация, которой он принадлежит. Используйте её id как ORG_ID в примерах ниже.
Не храните ключи в системе контроля версий
Аудит шаг за шагом
1. Запустите аудит
Передайте ID подключённого репозитория и, при необходимости, ветку, тег или SHA коммита. Без ref проверяется ветка по умолчанию. API отвечает 202 Accepted и возвращает аудит, поставленный в очередь. Если аудит того же коммита уже выполняется, вы получите его, а не дубликат. Передайте "mode": "FULL" для полной проверки: она расходует 1 кредит владельца рабочего пространства и обязательна для ref, отличного от ветки по умолчанию. Без этого API запускает бесплатный Quick Scan (posture, gitleaks и osv на последнем коммите ветки по умолчанию), пока не исчерпан месячный лимит владельца. Полная проверка без достаточного количества кредитов возвращает 402 INSUFFICIENT_CREDITS.
analyzers задаёт проверки для запуска из набора «Безопасность» (posture, gitleaks, secrets-history, osv, vendored, eol, supply-chain, sast, sast-community, bandit, gosec, rust-audit, iac, base-images, workflows), набора «Качество кода» (code-smells, complexity, duplication, tests, docs, accessibility, performance, hygiene), набора «Устойчивость» (licenses, dep-health, activity), набора «Риски ИИ-кода» (hallucinated-deps, ai-slop, vibe-stack, llm-app, ai-signal) и набора «Готовность к продакшену» (resilience, data-access, operability, openapi, web-assets). Дополнительные неоцениваемые наборы «Конфиденциальность и защита данных» (бета) (privacy-exposure, privacy-flows, privacy-lifecycle) и «История Git» (git-history) выбираются так же. Если не передавать этот параметр, запускаются проверки репозитория по умолчанию. GET /orgs/$ORG_ID/analyzers возвращает список всех проверок с признаком доступности на сервере; запрос недоступной проверки возвращает 422 ANALYZER_UNAVAILABLE.
curl -X POST https://api.vetkit.dev/v1/orgs/$ORG_ID/audits \ -H "Authorization: Bearer $VETKIT_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"repositoryId\": \"$REPO_ID\", \"ref\": \"main\", \"analyzers\": [\"gitleaks\", \"osv\", \"sast\"]}"{ "id": "0192f3a4-5b6c-7d8e-9f01-23456789abcd", "status": "QUEUED", "ref": "main", "commitSha": "9f3c2e1b7a0d4c55e2f8a61b3d9c07e4a5b6f812", "repository": { "fullName": "acme/payments-api", "htmlUrl": "https://github.com/acme/payments-api" }, "analyzers": ["gitleaks", "osv", "sast"], "steps": [], "summary": null}2. Опрашивайте до завершения
Опрашивайте каждые несколько секунд, пока status не станет SUCCEEDED, FAILED или CANCELLED. Завершённый аудит содержит summary.grade, summary.overallScore, summary.suiteScores (оценка и балл каждого выполненного набора проверок) и количество находок по критичности.
while :; do STATUS=$(curl -s https://api.vetkit.dev/v1/orgs/$ORG_ID/audits/$AUDIT_ID \ -H "Authorization: Bearer $VETKIT_API_KEY" | jq -r .status) echo "$STATUS" case "$STATUS" in SUCCEEDED|FAILED|CANCELLED) break ;; esac sleep 3done3. Скачайте отчёт
Выберите format=json для машиночитаемой сводки, markdown для читаемого отчёта, sarif для SARIF 2.1.0 или pdf для отчёта, готового к печати (язык задаётся параметром locale: en, de, es, fr, it, pt, ru или tr).
curl "https://api.vetkit.dev/v1/orgs/$ORG_ID/audits/$AUDIT_ID/report?format=sarif" \ -H "Authorization: Bearer $VETKIT_API_KEY" \ -o vetkit.sarifЗагрузите файл с помощью action github/codeql-action/upload-sarif от GitHub, чтобы видеть находки в оповещениях code scanning вашего репозитория.
Основные эндпоинты
Пути указаны относительно https://api.vetkit.dev/v1. Параметры и схемы ответов описаны в документе OpenAPI.
| Метод | Путь | Описание | Область доступа |
|---|---|---|---|
| GET | /me | Определить ключ и его организацию | любая |
| GET | /orgs/{orgId}/repos | Список подключённых репозиториев | repos:read |
| POST | /orgs/{orgId}/repos | Подключить репозиторий по URL | repos:write |
| GET | /orgs/{orgId}/analyzers | Проверки по наборам с доступностью и значениями по умолчанию | audits:read |
| POST | /orgs/{orgId}/audits | Запустить аудит (202 Accepted) | audits:write |
| GET | /orgs/{orgId}/audits | Список аудитов с фильтром по репозиторию или статусу | audits:read |
| GET | /orgs/{orgId}/audits/{auditId} | Статус, шаги и сводка аудита | audits:read |
| POST | /orgs/{orgId}/audits/{auditId}/cancel | Отменить аудит в очереди или выполняющийся аудит | audits:write |
| DELETE | /orgs/{orgId}/audits/{auditId} | Безвозвратно удалить завершённый аудит и его отчёт | audits:write |
| GET | /orgs/{orgId}/audits/{auditId}/findings | Находки с фильтрами по критичности, набору проверок, категории и другим полям; с пагинацией | findings:read |
| GET | /orgs/{orgId}/audits/{auditId}/report | Отчёт в формате json, markdown, sarif или pdf | reports:read |
При подключении репозитория, владелец которого не установил GitHub App, возвращается 409 INSTALLATION_REQUIRED с installUrl в details.
Пагинация
Эндпоинты списков используют курсорную пагинацию. Передайте limit (1–100, по умолчанию 25), а для следующей страницы — значение nextCursor из предыдущего ответа в параметре cursor. Если nextCursor равен null, вы дошли до конца.
{ "items": [ … ], "nextCursor": "eyJpZCI6…" }Ошибки
Ошибки возвращаются в формате application/problem+json со стабильным машиночитаемым полем code. Указывайте requestId, когда обращаетесь в поддержку.
{ "type": "https://vetkit.dev/problems/insufficient-scope", "title": "Forbidden", "status": 403, "detail": "This API key is missing the audits:write scope.", "code": "INSUFFICIENT_SCOPE", "requestId": "req_01J9Z3K8V4M2"}Частые коды: API_KEY_INVALID, API_KEY_REVOKED, API_KEY_EXPIRED, INSUFFICIENT_SCOPE, VALIDATION_FAILED, NOT_FOUND, INSTALLATION_REQUIRED, AUDIT_CONCURRENCY_LIMIT, INSUFFICIENT_CREDITS и RATE_LIMITED.
Лимиты запросов
- На ключ: по умолчанию 60 запросов в минуту; при создании ключа можно задать до 600.
- Одновременные аудиты: до 3 аудитов в очереди или в работе на организацию; при превышении возвращается
409 AUDIT_CONCURRENCY_LIMIT. - Запуски аудитов: 30 в час на организацию.
При превышении лимита запросов возвращается 429 RATE_LIMITED с заголовком Retry-After — подождите указанное число секунд, прежде чем повторить запрос. Во время беты лимиты могут меняться.