Vai al contenuto

Documentazione · API REST

API REST

Un’API JSON su HTTPS per tutto ciò che fa l’app vetkit. Usala per avviare audit dalla CI, bloccare i rilasci in base al voto o inviare SARIF al code scanning di GitHub.

Panoramica

URL di basehttps://api.vetkit.dev/v1
OpenAPIhttps://api.vetkit.dev/v1/openapi.json — il riferimento completo e leggibile dalle macchine per ogni route e schema
FormatoCorpi di richiesta e risposta in JSON, timestamp ISO 8601, ID UUID
ErroriRFC 9457 application/problem+json

Questa pagina tratta gli aspetti essenziali. Genera un client o consulta i singoli schemi dal documento OpenAPI; il server MCP è costruito sulla stessa API.

Autenticazione

Crea una chiave in Impostazioni dello spazio di lavoro → Chiavi API (solo proprietari e amministratori) e inviala come token Bearer. Le chiavi appartengono a un’organizzazione e hanno ambiti espliciti: repos:read, repos:write, audits:read, audits:write, audits:run, findings:read, findings:write, findings:ai-fix, reports:read e agent:check.

Verifica la tua chiave
curl https://api.vetkit.dev/v1/me \  -H "Authorization: Bearer $VETKIT_API_KEY"

La risposta elenca gli ambiti della chiave e, in organizations, l’organizzazione a cui appartiene — usa quell’id come ORG_ID qui sotto.

Tieni le chiavi fuori dal controllo di versione

Conserva le chiavi nell’archivio dei segreti del tuo provider CI, mai nel codice. Il segreto viene mostrato una sola volta e memorizzato solo come hash; se viene esposto, revocalo nell’app — la revoca è immediata.

Un audit passo per passo

1. Avvia un audit

Passa l’ID di un repository collegato e, facoltativamente, un branch, un tag o uno SHA di commit. Senza ref viene sottoposto ad audit il branch predefinito. L’API risponde con 202 Accepted e l’audit in coda. Se è già in esecuzione un audit per lo stesso commit, ricevi quello invece di un duplicato. Invia "mode": "FULL" per una scansione completa, che usa 1 credito del proprietario dello spazio di lavoro ed è obbligatoria per un ref diverso dal branch predefinito. Senza questo campo l’API esegue un Quick Scan gratuito (posture, gitleaks e osv sull’ultimo commit del branch predefinito) finché dura la quota mensile del proprietario. Una scansione completa senza crediti sufficienti restituisce 402 INSUFFICIENT_CREDITS.

analyzers sceglie i controlli da eseguire tra quelli della suite Sicurezza (posture, gitleaks, secrets-history, osv, vendored, eol, supply-chain, sast, sast-community, bandit, gosec, rust-audit, iac, base-images, workflows), della suite Qualità del codice (code-smells, complexity, duplication, tests, docs, accessibility, performance, hygiene), della suite Sostenibilità (licenses, dep-health, activity), della suite Rischi del codice IA (hallucinated-deps, ai-slop, vibe-stack, llm-app, ai-signal) e della suite Pronto per la produzione (resilience, data-access, operability, openapi, web-assets). Le suite opzionali e senza punteggio Privacy e protezione dei dati (beta) (privacy-exposure, privacy-flows, privacy-lifecycle) e Cronologia Git (git-history) si selezionano allo stesso modo. Omettilo per eseguire i controlli predefiniti del repository. GET /orgs/$ORG_ID/analyzers elenca tutti i controlli e indica se sono disponibili sul server; richiederne uno non disponibile restituisce 422 ANALYZER_UNAVAILABLE.

Crea un audit
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. Controlla lo stato fino al termine

Ripeti la richiesta ogni pochi secondi finché status non è SUCCEEDED, FAILED o CANCELLED. Un audit concluso include summary.grade, summary.overallScore, summary.suiteScores (voto e punteggio di ogni suite eseguita) e i conteggi per gravità.

Polling con 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. Scarica il report

Scegli format=json per il riepilogo leggibile dalle macchine, markdown per un report leggibile, sarif per SARIF 2.1.0 oppure pdf per un report pronto per la stampa (imposta locale su en, de, es, fr, it, pt, ru o tr per sceglierne la lingua).

Scarica il 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

Carica il file con l’action github/codeql-action/upload-sarif di GitHub per vedere i rilevamenti negli avvisi di code scanning del tuo repository.

Endpoint principali

I percorsi sono relativi a https://api.vetkit.dev/v1. Consulta il documento OpenAPI per parametri e schemi di risposta.

MetodoPercorsoDescrizioneAmbito
GET/meIdentifica la chiave e la sua organizzazionequalsiasi
GET/orgs/{orgId}/reposElenca i repository collegatirepos:read
POST/orgs/{orgId}/reposCollega un repository tramite URLrepos:write
GET/orgs/{orgId}/analyzersControlli per suite, con disponibilità e impostazioni predefiniteaudits:read
POST/orgs/{orgId}/auditsAvvia un audit (202 Accepted)audits:write
GET/orgs/{orgId}/auditsElenca gli audit, con filtro per repository o statoaudits:read
GET/orgs/{orgId}/audits/{auditId}Stato, passaggi e riepilogo dell’auditaudits:read
POST/orgs/{orgId}/audits/{auditId}/cancelAnnulla un audit in coda o in esecuzioneaudits:write
DELETE/orgs/{orgId}/audits/{auditId}Elimina definitivamente un audit concluso e il relativo reportaudits:write
GET/orgs/{orgId}/audits/{auditId}/findingsRilevamenti, filtrabili per gravità, suite, categoria e altro; paginatifindings:read
GET/orgs/{orgId}/audits/{auditId}/reportReport in json, markdown, sarif o pdfreports:read

Collegare un repository il cui proprietario non ha installato la GitHub App restituisce 409 INSTALLATION_REQUIRED con un installUrl in details.

Paginazione

Gli endpoint di elenco usano la paginazione a cursore. Passa limit (1–100, predefinito 25) e, per la pagina successiva, il nextCursor della risposta precedente come cursor. Un nextCursor uguale a null significa che hai raggiunto la fine.

Struttura della pagina
{ "items": [ … ], "nextCursor": "eyJpZCI6…" }

Errori

Gli errori usano application/problem+json con un code stabile e leggibile dalle macchine. Includi il requestId quando contatti l’assistenza.

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

Codici comuni: 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.

Limiti di frequenza

  • Per chiave: 60 richieste al minuto per impostazione predefinita, configurabili fino a 600 quando crei la chiave.
  • Audit simultanei: fino a 3 audit in coda o in esecuzione per organizzazione; oltre questo limite viene restituito 409 AUDIT_CONCURRENCY_LIMIT.
  • Avvii di audit: 30 all’ora per organizzazione.

Il superamento di un limite di frequenza restituisce 429 RATE_LIMITED con un header Retry-After — attendi quel numero di secondi prima di riprovare. I limiti possono cambiare durante la beta.

Richiedi l’accesso anticipato

Raccontaci qualcosa del tuo team e dei repository che vuoi sottoporre ad audit. Accogliamo i team a piccoli gruppi e ti risponderemo via email.

Usiamo questi dati solo per rispondere alla tua richiesta. Informativa sulla privacy