İçeriğe atla

Dokümantasyon · REST API

REST API

vetkit uygulamasının yaptığı her şey için HTTPS üzerinden JSON tabanlı bir API. Denetimleri CI üzerinden başlatmak, sürüm yayınını bir not eşiğine bağlamak veya SARIF dosyalarını GitHub code scanning’e göndermek için kullanın.

Genel bakış

Temel URLhttps://api.vetkit.dev/v1
OpenAPIhttps://api.vetkit.dev/v1/openapi.json — tüm rotalar ve şemalar için eksiksiz, makine tarafından okunabilir referans
BiçimJSON istek ve yanıt gövdeleri, ISO 8601 zaman damgaları, UUID kimlikleri
HatalarRFC 9457 application/problem+json

Bu sayfa temel konuları kapsar. OpenAPI belgesinden bir istemci oluşturun veya şemalara tek tek göz atın; MCP sunucusu da aynı API üzerine kuruludur.

Kimlik doğrulama

Çalışma alanı ayarları → API anahtarları sayfasında bir anahtar oluşturun (yalnızca sahipler ve yöneticiler) ve anahtarı Bearer token olarak gönderin. Anahtarlar tek bir kuruluşa aittir ve açıkça tanımlanmış kapsamlar taşır: repos:read, repos:write, audits:read, audits:write, audits:run, findings:read, findings:write, findings:ai-fix, reports:read ve agent:check.

Anahtarınızı kontrol edin
curl https://api.vetkit.dev/v1/me \  -H "Authorization: Bearer $VETKIT_API_KEY"

Yanıt, anahtarın kapsamlarını ve organizations altında anahtarın ait olduğu kuruluşu listeler — aşağıda ORG_ID olarak bu id değerini kullanın.

Anahtarları kaynak kontrolünün dışında tutun

Anahtarları asla kodda değil, CI sağlayıcınızın gizli bilgi kasasında saklayın. Gizli değer yalnızca bir kez gösterilir ve yalnızca hash olarak saklanır; sızarsa uygulamadan iptal edin — iptal anında geçerli olur.

Adım adım denetim

1. Denetim başlatın

Bağlı bir deponun kimliğini ve isteğe bağlı olarak bir dal, etiket veya commit SHA’sı iletin. ref verilmezse varsayılan dal denetlenir. API, 202 Accepted ve kuyruğa alınan denetimle yanıt verir. Aynı commit için zaten çalışan bir denetim varsa, yinelenen bir denetim yerine o denetim döndürülür. Tam tarama için "mode": "FULL" gönderin; tam tarama çalışma alanı sahibinden 1 kredi kullanır ve varsayılan dal dışındaki bir ref için gereklidir. Bu alan olmadan API, sahibin aylık hakkı sürdükçe ücretsiz bir Quick Scan (varsayılan dalın son commit’inde posture, gitleaks ve osv) çalıştırır. Yeterli kredi olmadan başlatılan tam tarama 402 INSUFFICIENT_CREDITS döndürür.

analyzers alanı çalıştırılacak kontrolleri seçer: Güvenlik grubundan (posture, gitleaks, secrets-history, osv, vendored, eol, supply-chain, sast, sast-community, bandit, gosec, rust-audit, iac, base-images, workflows), Kod kalitesi grubundan (code-smells, complexity, duplication, tests, docs, accessibility, performance, hygiene), Sürdürülebilirlik grubundan (licenses, dep-health, activity), Yapay zekâ kod riskleri grubundan (hallucinated-deps, ai-slop, vibe-stack, llm-app, ai-signal) ve Canlıya hazırlık grubundan (resilience, data-access, operability, openapi, web-assets). Nota etki etmeyen, isteğe bağlı Gizlilik ve Veri Koruma (beta) grubu (privacy-exposure, privacy-flows, privacy-lifecycle) ile Git geçmişi grubu (git-history) da aynı şekilde seçilir. Bu alanı göndermezseniz deponun varsayılan kontrolleri çalışır. GET /orgs/$ORG_ID/analyzers tüm kontrolleri ve her birinin sunucuda kullanılabilir olup olmadığını listeler; kullanılamayan bir kontrolü istemek 422 ANALYZER_UNAVAILABLE döndürür.

Denetim oluşturun
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. Bitene kadar sorgulayın

status değeri SUCCEEDED, FAILED veya CANCELLED olana kadar birkaç saniyede bir sorgulayın. Tamamlanmış bir denetim; summary.grade, summary.overallScore ve summary.suiteScores (çalışan her grubun notu ve puanı) alanlarını ve önem derecesine göre bulgu sayılarını içerir.

curl ve jq ile sorgulayın
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. Raporu indirin

Makine tarafından okunabilir özet için format=json, okunabilir bir rapor için markdown, SARIF 2.1.0 için sarif ya da yazdırmaya hazır bir rapor için pdf seçin (raporun dili için locale parametresini en, de, es, fr, it, pt, ru veya tr olarak ayarlayın).

SARIF indirin
curl "https://api.vetkit.dev/v1/orgs/$ORG_ID/audits/$AUDIT_ID/report?format=sarif" \  -H "Authorization: Bearer $VETKIT_API_KEY" \  -o vetkit.sarif

Bulguları deponuzun code scanning uyarılarında görmek için dosyayı GitHub’ın github/codeql-action/upload-sarif action’ıyla yükleyin.

Temel uç noktalar

Yollar https://api.vetkit.dev/v1 adresine görelidir. Parametreler ve yanıt şemaları için OpenAPI belgesine bakın.

MetotYolAçıklamaKapsam
GET/meAnahtarı ve kuruluşunu tanımlarherhangi biri
GET/orgs/{orgId}/reposBağlı depoları listelerrepos:read
POST/orgs/{orgId}/reposURL ile bir depo bağlarrepos:write
GET/orgs/{orgId}/analyzersKontrolleri gruplara göre, kullanılabilirlik ve varsayılan bilgileriyle listeleraudits:read
POST/orgs/{orgId}/auditsDenetim başlatır (202 Accepted)audits:write
GET/orgs/{orgId}/auditsDenetimleri listeler; depoya veya duruma göre filtreleraudits:read
GET/orgs/{orgId}/audits/{auditId}Denetim durumu, adımları ve özetiaudits:read
POST/orgs/{orgId}/audits/{auditId}/cancelKuyruktaki veya çalışan bir denetimi iptal ederaudits:write
DELETE/orgs/{orgId}/audits/{auditId}Tamamlanmış bir denetimi ve raporunu kalıcı olarak sileraudits:write
GET/orgs/{orgId}/audits/{auditId}/findingsBulguları listeler; önem derecesine, gruba, kategoriye ve diğer alanlara göre filtrelenebilir; sayfalıdırfindings:read
GET/orgs/{orgId}/audits/{auditId}/reportRaporu json, markdown, sarif veya pdf olarak döndürürreports:read

Sahibi GitHub App’i kurmamış bir depoyu bağlamaya çalışmak, details içinde bir installUrl ile birlikte 409 INSTALLATION_REQUIRED döndürür.

Sayfalama

Liste uç noktaları imleç tabanlı sayfalama kullanır. limit (1–100, varsayılan 25) ve sonraki sayfa için önceki yanıttaki nextCursor değerini cursor olarak iletin. nextCursor değerinin null olması sona ulaştığınız anlamına gelir.

Sayfa yapısı
{ "items": [ … ], "nextCursor": "eyJpZCI6…" }

Hatalar

Hatalar, kararlı ve makine tarafından okunabilir bir code alanıyla application/problem+json biçimini kullanır. Destek ekibiyle iletişime geçerken requestId değerini ekleyin.

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

Sık karşılaşılan kodlar: API_KEY_INVALID, API_KEY_REVOKED, API_KEY_EXPIRED, INSUFFICIENT_SCOPE, VALIDATION_FAILED, NOT_FOUND, INSTALLATION_REQUIRED, AUDIT_CONCURRENCY_LIMIT, INSUFFICIENT_CREDITS ve RATE_LIMITED.

Hız sınırları

  • Anahtar başına: varsayılan olarak dakikada 60 istek; anahtarı oluştururken 600’e kadar yapılandırılabilir.
  • Eşzamanlı denetimler: kuruluş başına kuyrukta veya çalışır durumda en fazla 3 denetim; fazlası 409 AUDIT_CONCURRENCY_LIMIT döndürür.
  • Denetim başlatma: kuruluş başına saatte 30.

Bir hız sınırının aşılması, Retry-After başlığıyla birlikte 429 RATE_LIMITED döndürür — yeniden denemeden önce belirtilen saniye kadar bekleyin. Sınırlar beta süresince değişebilir.

Erken erişim talep edin

Ekibinizden ve denetlemek istediğiniz depolardan kısaca bahsedin. Ekipleri küçük gruplar halinde aramıza alıyoruz; size e-postayla dönüş yapacağız.

Bu bilgileri yalnızca talebinize yanıt vermek için kullanırız. Gizlilik politikası