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 URL	`https://api.vetkit.dev/v1`
OpenAPI	`https://api.vetkit.dev/v1/openapi.json` — the full, machine-readable reference for every route and schema
Format	JSON request and response bodies, ISO 8601 timestamps, UUID ids
Errors	RFC 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 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, findings:read, findings:write and reports:read.

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.

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

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

Poll every few seconds until status is SUCCEEDED, FAILED or CANCELLED. A finished audit includes summary.grade, summary.overallScore 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 3$ done

3. Download the report

Choose format=json for the machine-readable summary, markdown for a readable report, or sarif for SARIF 2.1.0.

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.

Method	Path	Description	Scope
GET	/me	Identify the key and its organization	any
GET	/orgs/{orgId}/repos	List connected repositories	repos:read
POST	/orgs/{orgId}/repos	Connect a repository by URL	repos:write
POST	/orgs/{orgId}/audits	Start an audit (202 Accepted)	audits:write
GET	/orgs/{orgId}/audits	List audits, filter by repository or status	audits:read
GET	/orgs/{orgId}/audits/{auditId}	Audit status, steps and summary	audits:read
POST	/orgs/{orgId}/audits/{auditId}/cancel	Cancel a queued or running audit	audits:write
DELETE	/orgs/{orgId}/audits/{auditId}	Permanently delete a finished audit and its report	audits:write
GET	/orgs/{orgId}/audits/{auditId}/findings	Findings, filterable and paginated	findings:read
GET	/orgs/{orgId}/audits/{auditId}/report	Report as json, markdown or sarif	reports: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 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; the pricing section lists the current values.