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 base	`https://api.vetkit.dev/v1`
OpenAPI	`https://api.vetkit.dev/v1/openapi.json` — il riferimento completo e leggibile dalle macchine per ogni route e schema
Formato	Corpi di richiesta e risposta in JSON, timestamp ISO 8601, ID UUID
Errori	RFC 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 → 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, findings:read, findings:write e reports:read.

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.

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

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

Controlla lo stato a intervalli di pochi secondi finché status non è SUCCEEDED, FAILED o CANCELLED. Un audit concluso include summary.grade, summary.overallScore 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 3$ done

3. Scarica il report

Scegli format=json per il riepilogo leggibile dalle macchine, markdown per un report leggibile o sarif per SARIF 2.1.0.

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.

Metodo	Percorso	Descrizione	Ambito
GET	/me	Identifica la chiave e la sua organizzazione	qualsiasi
GET	/orgs/{orgId}/repos	Elenca i repository collegati	repos:read
POST	/orgs/{orgId}/repos	Collega un repository tramite URL	repos:write
POST	/orgs/{orgId}/audits	Avvia un audit (202 Accepted)	audits:write
GET	/orgs/{orgId}/audits	Elenca gli audit, con filtro per repository o stato	audits:read
GET	/orgs/{orgId}/audits/{auditId}	Stato, passaggi e riepilogo dell’audit	audits:read
POST	/orgs/{orgId}/audits/{auditId}/cancel	Annulla un audit in coda o in esecuzione	audits:write
DELETE	/orgs/{orgId}/audits/{auditId}	Elimina definitivamente un audit concluso e il relativo report	audits:write
GET	/orgs/{orgId}/audits/{auditId}/findings	Rilevamenti, filtrabili e paginati	findings:read
GET	/orgs/{orgId}/audits/{auditId}/report	Report in json, markdown o sarif	reports: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 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; la sezione prezzi riporta i valori attuali.