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 → 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, findings:read, findings:write e reports:read.

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.

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

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. 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 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 3$ done

3. Baixe o relatório

Escolha format=json para o resumo legível por máquina, markdown para um relatório legível ou sarif para SARIF 2.1.0.

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é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
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, filtráveis e paginados	findings:read
GET	/orgs/{orgId}/audits/{auditId}/report	Relatório em json, markdown ou sarif	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.

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 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; a seção de preços lista os valores atuais.