Перейти к содержимому

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

REST API

JSON-API поверх HTTPS для всего, что делает приложение vetkit. Запускайте аудиты из CI, блокируйте релизы по оценке или отправляйте SARIF в GitHub code scanning.

Обзор

Базовый URLhttps://api.vetkit.dev/v1
OpenAPIhttps://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 в примерах ниже.

Не храните ключи в системе контроля версий

Храните ключи в хранилище секретов вашего CI-провайдера, а не в коде. Секрет показывается один раз и хранится только в виде хеша; при утечке отзовите ключ в приложении — отзыв действует мгновенно.

Аудит шаг за шагом

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\"]}"
202 Accepted
{  "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 (оценка и балл каждого выполненного набора проверок) и количество находок по критичности.

Опрос с помощью curl и jq
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 3done

3. Скачайте отчёт

Выберите format=json для машиночитаемой сводки, markdown для читаемого отчёта, sarif для SARIF 2.1.0 или pdf для отчёта, готового к печати (язык задаётся параметром locale: en, de, es, fr, it, pt, ru или tr).

Скачивание SARIF
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Подключить репозиторий по URLrepos: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 или pdfreports:read

При подключении репозитория, владелец которого не установил GitHub App, возвращается 409 INSTALLATION_REQUIRED с installUrl в details.

Пагинация

Эндпоинты списков используют курсорную пагинацию. Передайте limit (1–100, по умолчанию 25), а для следующей страницы — значение nextCursor из предыдущего ответа в параметре cursor. Если nextCursor равен null, вы дошли до конца.

Структура страницы
{ "items": [ … ], "nextCursor": "eyJpZCI6…" }

Ошибки

Ошибки возвращаются в формате application/problem+json со стабильным машиночитаемым полем code. Указывайте requestId, когда обращаетесь в поддержку.

403 Forbidden
{  "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 — подождите указанное число секунд, прежде чем повторить запрос. Во время беты лимиты могут меняться.

Запросить ранний доступ

Расскажите немного о своей команде и репозиториях, которые хотите проверять. Мы подключаем команды небольшими группами и ответим по электронной почте.

Мы используем эти данные только для ответа на ваш запрос. Политика конфиденциальности