Skip to content

Docs · REST API

REST API

A JSON-over-HTTPS API for everything the vetkit app does. Use it to start audits from CI, gate releases on a grade, or push SARIF into GitHub code scanning.

Overview

Base URLhttps://api.vetkit.dev/v1
OpenAPIhttps://api.vetkit.dev/v1/openapi.json — the full, machine-readable reference for every route and schema
FormatJSON request and response bodies, ISO 8601 timestamps, UUID ids
ErrorsRFC 9457 application/problem+json

This page covers the essentials. Generate a client or browse individual schemas from the OpenAPI document; the MCP server is built on the same API.

Authentication

Create a key in Workspace settings → API keys (owners and admins only) and send it as a Bearer token. Keys belong to one organization and carry explicit scopes: repos:read, repos:write, audits:read, audits:write, audits:run, findings:read, findings:write, findings:ai-fix, reports:read and agent:check.

Check your key
curl https://api.vetkit.dev/v1/me \  -H "Authorization: Bearer $VETKIT_API_KEY"

The response lists the key’s scopes and, under organizations, the organization it belongs to — use that id as ORG_ID below.

Keep keys out of source control

Store keys in your CI provider’s secret store, never in code. The secret is shown once and stored only as a hash; if it leaks, revoke it in the app — revocation is immediate.

Audit walkthrough

1. Start an audit

Pass a connected repository id and, optionally, a branch, tag or commit SHA. Without ref the default branch is audited. The API responds with 202 Accepted and the queued audit. If an audit for the same commit is already running, you get that one back instead of a duplicate. Send "mode": "FULL" for a full scan, which uses 1 credit from the workspace owner and is required for a ref other than the default branch. Without it the API runs a free Quick Scan (posture, gitleaks and osv on the latest default-branch commit) while the owner’s monthly allowance lasts. A full scan without enough credits returns 402 INSUFFICIENT_CREDITS.

analyzers picks the checks to run, from the Security suite (posture, gitleaks, secrets-history, osv, vendored, eol, supply-chain, sast, sast-community, bandit, gosec, rust-audit, iac, base-images, workflows), the Code quality suite (code-smells, complexity, duplication, tests, docs, accessibility, performance, hygiene), the Sustainability suite (licenses, dep-health, activity), the AI code risks suite (hallucinated-deps, ai-slop, vibe-stack, llm-app, ai-signal) and the Production readiness suite (resilience, data-access, operability, openapi, web-assets). The opt-in, unscored Privacy & Data Protection (beta) suite (privacy-exposure, privacy-flows, privacy-lifecycle) and Git history suite (git-history) are selected the same way. Leave it out to run the repository’s default checks. GET /orgs/$ORG_ID/analyzers lists every check and whether it is available on the server; asking for one that is not returns 422 ANALYZER_UNAVAILABLE.

Create an 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. Poll until it finishes

Poll every few seconds until status is SUCCEEDED, FAILED or CANCELLED. A finished audit includes summary.grade, summary.overallScore, summary.suiteScores (grade and score for each suite that ran) and counts by severity.

Poll with curl and 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. Download the report

Choose format=json for the machine-readable summary, markdown for a readable report, sarif for SARIF 2.1.0, or pdf for a print-ready report (set locale to en, de, es, fr, it, pt, ru or tr for its language).

Download 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

Upload the file with GitHub’s github/codeql-action/upload-sarif action to see findings in your repository’s code scanning alerts.

Key endpoints

Paths are relative to https://api.vetkit.dev/v1. See the OpenAPI document for parameters and response schemas.

MethodPathDescriptionScope
GET/meIdentify the key and its organizationany
GET/orgs/{orgId}/reposList connected repositoriesrepos:read
POST/orgs/{orgId}/reposConnect a repository by URLrepos:write
GET/orgs/{orgId}/analyzersChecks by suite, with availability and defaultsaudits:read
POST/orgs/{orgId}/auditsStart an audit (202 Accepted)audits:write
GET/orgs/{orgId}/auditsList audits, filter by repository or statusaudits:read
GET/orgs/{orgId}/audits/{auditId}Audit status, steps and summaryaudits:read
POST/orgs/{orgId}/audits/{auditId}/cancelCancel a queued or running auditaudits:write
DELETE/orgs/{orgId}/audits/{auditId}Permanently delete a finished audit and its reportaudits:write
GET/orgs/{orgId}/audits/{auditId}/findingsFindings, filterable by severity, suite, category and more; paginatedfindings:read
GET/orgs/{orgId}/audits/{auditId}/reportReport as json, markdown, sarif or pdfreports:read

Connecting a repository whose owner has not installed the GitHub App returns 409 INSTALLATION_REQUIRED with an installUrl in details.

Pagination

List endpoints are cursor-paginated. Pass limit (1–100, default 25) and, for the next page, the nextCursor from the previous response as cursor. A null nextCursor means you have reached the end.

Page shape
{ "items": [ … ], "nextCursor": "eyJpZCI6…" }

Errors

Errors use application/problem+json with a stable, machine-readable code. Include the requestId when you contact support.

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

Common codes: API_KEY_INVALID, API_KEY_REVOKED, API_KEY_EXPIRED, INSUFFICIENT_SCOPE, VALIDATION_FAILED, NOT_FOUND, INSTALLATION_REQUIRED, AUDIT_CONCURRENCY_LIMIT, INSUFFICIENT_CREDITS and RATE_LIMITED.

Rate limits

  • Per key: 60 requests per minute by default, configurable up to 600 when you create the key.
  • Concurrent audits: up to 3 queued or running audits per organization; more returns 409 AUDIT_CONCURRENCY_LIMIT.
  • Audit starts: 30 per hour per organization.

Exceeding a rate limit returns 429 RATE_LIMITED with a Retry-After header — wait that many seconds before retrying. Limits may change during the beta.

Request early access

Tell us a little about your team and the repositories you want to audit. We onboard teams in small batches and will reply by email.

We use these details only to reply to your request. Privacy policy