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 URL | https://api.vetkit.dev/v1 |
|---|---|
| OpenAPI | https://api.vetkit.dev/v1/openapi.json — tüm rotalar ve şemalar için eksiksiz, makine tarafından okunabilir referans |
| Biçim | JSON istek ve yanıt gövdeleri, ISO 8601 zaman damgaları, UUID kimlikleri |
| Hatalar | RFC 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.
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
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.
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. 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.
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. 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).
curl "https://api.vetkit.dev/v1/orgs/$ORG_ID/audits/$AUDIT_ID/report?format=sarif" \ -H "Authorization: Bearer $VETKIT_API_KEY" \ -o vetkit.sarifBulguları 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.
| Metot | Yol | Açıklama | Kapsam |
|---|---|---|---|
| GET | /me | Anahtarı ve kuruluşunu tanımlar | herhangi biri |
| GET | /orgs/{orgId}/repos | Bağlı depoları listeler | repos:read |
| POST | /orgs/{orgId}/repos | URL ile bir depo bağlar | repos:write |
| GET | /orgs/{orgId}/analyzers | Kontrolleri gruplara göre, kullanılabilirlik ve varsayılan bilgileriyle listeler | audits:read |
| POST | /orgs/{orgId}/audits | Denetim başlatır (202 Accepted) | audits:write |
| GET | /orgs/{orgId}/audits | Denetimleri listeler; depoya veya duruma göre filtreler | audits:read |
| GET | /orgs/{orgId}/audits/{auditId} | Denetim durumu, adımları ve özeti | audits:read |
| POST | /orgs/{orgId}/audits/{auditId}/cancel | Kuyruktaki veya çalışan bir denetimi iptal eder | audits:write |
| DELETE | /orgs/{orgId}/audits/{auditId} | Tamamlanmış bir denetimi ve raporunu kalıcı olarak siler | audits:write |
| GET | /orgs/{orgId}/audits/{auditId}/findings | Bulguları listeler; önem derecesine, gruba, kategoriye ve diğer alanlara göre filtrelenebilir; sayfalıdır | findings:read |
| GET | /orgs/{orgId}/audits/{auditId}/report | Raporu json, markdown, sarif veya pdf olarak döndürür | reports: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.
{ "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.
{ "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_LIMITdö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.