Pular para o conteúdo

Docs · API REST

API REST

Uma API JSON sobre HTTPS para tudo o que o app vetkit faz. Use-a para iniciar auditorias a partir do CI, condicionar releases a uma nota ou enviar SARIF para o code scanning do GitHub.

Visão geral

URL basehttps://api.vetkit.dev/v1
OpenAPIhttps://api.vetkit.dev/v1/openapi.json — a referência completa e legível por máquina de todas as rotas e esquemas
FormatoCorpos de requisição e de resposta em JSON, timestamps ISO 8601, ids UUID
ErrosRFC 9457 application/problem+json

Esta página cobre o essencial. Gere um cliente ou consulte esquemas individuais no documento OpenAPI; o servidor MCP é construído sobre a mesma API.

Autenticação

Crie uma chave em Configurações do espaço de trabalho → Chaves de API (apenas proprietários e administradores) e envie-a como um token Bearer. As chaves pertencem a uma organização e têm escopos explícitos: repos:read, repos:write, audits:read, audits:write, audits:run, findings:read, findings:write, findings:ai-fix, reports:read e agent:check.

Verifique sua chave
curl https://api.vetkit.dev/v1/me \  -H "Authorization: Bearer $VETKIT_API_KEY"

A resposta lista os escopos da chave e, em organizations, a organização à qual ela pertence — use esse id como ORG_ID abaixo.

Mantenha as chaves fora do controle de versão

Guarde as chaves no cofre de segredos do seu provedor de CI, nunca no código. O segredo é exibido uma única vez e armazenado apenas como hash; se ele vazar, revogue-o no app — a revogação é imediata.

Passo a passo de uma auditoria

1. Inicie uma auditoria

Passe o id de um repositório conectado e, opcionalmente, uma branch, tag ou SHA de commit. Sem ref, a branch padrão é auditada. A API responde com 202 Accepted e a auditoria enfileirada. Se uma auditoria do mesmo commit já estiver em execução, você recebe essa auditoria em vez de uma duplicata. Envie "mode": "FULL" para uma análise completa, que usa 1 crédito do proprietário do espaço de trabalho e é obrigatória para um ref diferente da branch padrão. Sem isso, a API executa um Quick Scan gratuito (posture, gitleaks e osv no commit mais recente da branch padrão) enquanto durar a cota mensal do proprietário. Uma análise completa sem créditos suficientes retorna 402 INSUFFICIENT_CREDITS.

analyzers escolhe as verificações a executar, da suíte Segurança (posture, gitleaks, secrets-history, osv, vendored, eol, supply-chain, sast, sast-community, bandit, gosec, rust-audit, iac, base-images, workflows), da suíte Qualidade do código (code-smells, complexity, duplication, tests, docs, accessibility, performance, hygiene), da suíte Sustentabilidade (licenses, dep-health, activity), da suíte Riscos de código de IA (hallucinated-deps, ai-slop, vibe-stack, llm-app, ai-signal) e da suíte Prontidão para produção (resilience, data-access, operability, openapi, web-assets). As suítes opcionais e sem pontuação Privacidade e proteção de dados (beta) (privacy-exposure, privacy-flows, privacy-lifecycle) e Histórico do Git (git-history) são escolhidas da mesma forma. Omita-o para executar as verificações padrão do repositório. GET /orgs/$ORG_ID/analyzers lista todas as verificações e se cada uma está disponível no servidor; pedir uma indisponível retorna 422 ANALYZER_UNAVAILABLE.

Criar uma auditoria
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. Consulte até terminar

Consulte a cada poucos segundos até que status seja SUCCEEDED, FAILED ou CANCELLED. Uma auditoria concluída inclui summary.grade, summary.overallScore, summary.suiteScores (nota e pontuação de cada suíte executada) e as contagens por severidade.

Consultar com curl e 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. Baixe o relatório

Escolha format=json para o resumo legível por máquina, markdown para um relatório legível, sarif para SARIF 2.1.0 ou pdf para um relatório pronto para impressão (defina locale como en, de, es, fr, it, pt, ru ou tr para escolher o idioma).

Baixar 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

Envie o arquivo com a action github/codeql-action/upload-sarif do GitHub para ver os achados nos alertas de code scanning do seu repositório.

Principais endpoints

Os caminhos são relativos a https://api.vetkit.dev/v1. Veja o documento OpenAPI para parâmetros e esquemas de resposta.

MétodoCaminhoDescriçãoEscopo
GET/meIdentifica a chave e sua organizaçãoqualquer
GET/orgs/{orgId}/reposLista os repositórios conectadosrepos:read
POST/orgs/{orgId}/reposConecta um repositório por URLrepos:write
GET/orgs/{orgId}/analyzersVerificações por suíte, com disponibilidade e padrõesaudits:read
POST/orgs/{orgId}/auditsInicia uma auditoria (202 Accepted)audits:write
GET/orgs/{orgId}/auditsLista auditorias, com filtro por repositório ou statusaudits:read
GET/orgs/{orgId}/audits/{auditId}Status, etapas e resumo da auditoriaaudits:read
POST/orgs/{orgId}/audits/{auditId}/cancelCancela uma auditoria na fila ou em execuçãoaudits:write
DELETE/orgs/{orgId}/audits/{auditId}Exclui permanentemente uma auditoria concluída e seu relatórioaudits:write
GET/orgs/{orgId}/audits/{auditId}/findingsAchados, com filtros por severidade, suíte, categoria e outros; paginadosfindings:read
GET/orgs/{orgId}/audits/{auditId}/reportRelatório em json, markdown, sarif ou pdfreports:read

Conectar um repositório cujo proprietário não instalou o GitHub App retorna 409 INSTALLATION_REQUIRED com uma installUrl em details.

Paginação

Os endpoints de listagem usam paginação por cursor. Passe limit (1–100, padrão 25) e, para a próxima página, o nextCursor da resposta anterior como cursor. Um nextCursor igual a null significa que você chegou ao fim.

Formato da página
{ "items": [ … ], "nextCursor": "eyJpZCI6…" }

Erros

Os erros usam application/problem+json com um code estável e legível por máquina. Inclua o requestId ao entrar em contato com o suporte.

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

Códigos comuns: API_KEY_INVALID, API_KEY_REVOKED, API_KEY_EXPIRED, INSUFFICIENT_SCOPE, VALIDATION_FAILED, NOT_FOUND, INSTALLATION_REQUIRED, AUDIT_CONCURRENCY_LIMIT, INSUFFICIENT_CREDITS e RATE_LIMITED.

Limites de taxa

  • Por chave: 60 requisições por minuto por padrão, configurável até 600 ao criar a chave.
  • Auditorias simultâneas: até 3 auditorias na fila ou em execução por organização; acima disso, a resposta é 409 AUDIT_CONCURRENCY_LIMIT.
  • Auditorias iniciadas: 30 por hora por organização.

Exceder um limite de taxa retorna 429 RATE_LIMITED com um cabeçalho Retry-After — aguarde esse número de segundos antes de tentar novamente. Os limites podem mudar durante o beta.

Solicite acesso antecipado

Conte um pouco sobre sua equipe e os repositórios que você quer auditar. Recebemos equipes em pequenos grupos e responderemos por e-mail.

Usamos esses dados apenas para responder à sua solicitação. Política de privacidade