Документация · 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, findings:read, findings:write и reports:read.

Проверка ключа

$ 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 и возвращает аудит, поставленный в очередь. Если аудит того же коммита уже выполняется, вы получите его, а не дубликат.

Создание аудита

$ 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\"}"

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" },  "steps": [],  "summary": null}

2. Опрашивайте до завершения

Опрашивайте API каждые несколько секунд, пока status не станет SUCCEEDED, FAILED или CANCELLED. Завершённый аудит содержит summary.grade, summary.overallScore и количество находок по уровням критичности.

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

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

Выберите format=json для машиночитаемой сводки, markdown для отчёта, удобного для чтения, или sarif для SARIF 2.1.0.

Скачивание 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	Подключить репозиторий по URL	repos:write
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	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, когда обращаетесь в поддержку.

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 и RATE_LIMITED.

Лимиты запросов

На ключ: по умолчанию 60 запросов в минуту; при создании ключа можно задать до 600.
Одновременные аудиты: до 3 аудитов в очереди или в работе на организацию; при превышении возвращается 409 AUDIT_CONCURRENCY_LIMIT.
Запуски аудитов: 30 в час на организацию.

При превышении лимита запросов возвращается 429 RATE_LIMITED с заголовком Retry-After — подождите указанное число секунд, прежде чем повторить запрос. Во время беты лимиты могут меняться; актуальные значения приведены в разделе с ценами.