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

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

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.

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

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. Bitene kadar sorgulayın

status değeri SUCCEEDED, FAILED veya CANCELLED olana kadar birkaç saniyede bir sorgulayın. Tamamlanan bir denetim summary.grade, summary.overallScore 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 3$ done

3. Raporu indirin

Makine tarafından okunabilir özet için format=json, okunabilir bir rapor için markdown veya SARIF 2.1.0 için sarif seçin.

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.

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
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; filtrelenebilir ve sayfalanmış	findings:read
GET	/orgs/{orgId}/audits/{auditId}/report	json, markdown veya sarif biçiminde rapor	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.

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 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; güncel değerler fiyatlandırma bölümünde listelenir.