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 base | https://api.vetkit.dev/v1 |
|---|---|
| OpenAPI | https://api.vetkit.dev/v1/openapi.json — a referência completa e legível por máquina de todas as rotas e esquemas |
| Formato | Corpos de requisição e de resposta em JSON, timestamps ISO 8601, ids UUID |
| Erros | RFC 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.
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
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.
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. 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.
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. 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).
curl "https://api.vetkit.dev/v1/orgs/$ORG_ID/audits/$AUDIT_ID/report?format=sarif" \ -H "Authorization: Bearer $VETKIT_API_KEY" \ -o vetkit.sarifEnvie 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étodo | Caminho | Descrição | Escopo |
|---|---|---|---|
| GET | /me | Identifica a chave e sua organização | qualquer |
| GET | /orgs/{orgId}/repos | Lista os repositórios conectados | repos:read |
| POST | /orgs/{orgId}/repos | Conecta um repositório por URL | repos:write |
| GET | /orgs/{orgId}/analyzers | Verificações por suíte, com disponibilidade e padrões | audits:read |
| POST | /orgs/{orgId}/audits | Inicia uma auditoria (202 Accepted) | audits:write |
| GET | /orgs/{orgId}/audits | Lista auditorias, com filtro por repositório ou status | audits:read |
| GET | /orgs/{orgId}/audits/{auditId} | Status, etapas e resumo da auditoria | audits:read |
| POST | /orgs/{orgId}/audits/{auditId}/cancel | Cancela uma auditoria na fila ou em execução | audits:write |
| DELETE | /orgs/{orgId}/audits/{auditId} | Exclui permanentemente uma auditoria concluída e seu relatório | audits:write |
| GET | /orgs/{orgId}/audits/{auditId}/findings | Achados, com filtros por severidade, suíte, categoria e outros; paginados | findings:read |
| GET | /orgs/{orgId}/audits/{auditId}/report | Relatório em json, markdown, sarif ou pdf | reports: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.
{ "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.
{ "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.