Skip to main content

​
Endpoint

POST /v1/scan/github

​
Request

​
Headers

HeaderValue
X-API-KeyYour ZenVeil API key
Content-Typeapplication/json

​
Body

{
  "repository": "owner/repo",
  "token": "ghp_optional_github_token",
  "ref": "main",
  "check_cves": false
}
FieldTypeRequiredDescription
repositorystringYesowner/repo, https://github.com/owner/repo, or SSH URL
tokenstringNoGitHub personal access token for private repositories
refstringNoBranch, tag, or commit SHA to scan. Defaults to default branch.
check_cvesbooleanNoQuery OSV.dev for known CVEs (default: false)

​
Response

{
  "scan_id": "a1b2c3d4e5f6",
  "status": "completed",
  "target_type": "github",
  "target": "owner/repo",
  "started_at": "2026-05-25T09:41:22Z",
  "completed_at": "2026-05-25T09:41:24Z",
  "finding_count": 3,
  "findings": [
    {
      "id": "ZG-A1B2C3",
      "category": "secrets",
      "severity": "CRITICAL",
      "title": "AWS access key",
      "description": "Potential secret or sensitive credential found in repository source.",
      "evidence": "AWS access key pattern matched; secret value redacted.",
      "location": {
        "target": "owner/repo",
        "path": "src/config.js",
        "line": 14,
        "column": 23,
        "url": null,
        "method": null
      },
      "scanner_name": "secrets",
      "remediation": "Revoke the AWS key and load it from a secret manager or environment variable.",
      "confidence": 0.95,
      "owasp_categories": ["A02:2021"]
    }
  ]
}

​
Examples

curl -X POST https://api.zenveil.dev/v1/scan/github \
  -H "X-API-Key: zvk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "owner/repo",
    "check_cves": true
  }'

​
Error responses

StatusErrorCause
400Bad requestInvalid repository format or missing required fields
400Archive download failedRepository doesn’t exist or isn’t accessible
403Access deniedPrivate repo requires --token with repo scope
404Repository not foundRepository name is wrong
429Rate limitGitHub API rate limit — add a token to increase limit
500Scan failedUnexpected error — retry