> ## Documentation Index
> Fetch the complete documentation index at: https:// zenveil.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/scan/github

> Scan a GitHub repository for secrets, supply chain risks, and OWASP vulnerabilities.

## Endpoint

```
POST /v1/scan/github
```

## Request

### Headers

| Header | Value |
| - | - |
| `X-API-Key` | Your ZenVeil API key |
| `Content-Type` | `application/json` |

### Body

```json theme={null}
{
  "repository": "owner/repo",
  "token": "ghp_optional_github_token",
  "ref": "main",
  "check_cves": false
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `repository` | string | Yes | `owner/repo`, `https://github.com/owner/repo`, or SSH URL |
| `token` | string | No | GitHub personal access token for private repositories |
| `ref` | string | No | Branch, tag, or commit SHA to scan. Defaults to default branch. |
| `check_cves` | boolean | No | Query OSV.dev for known CVEs (default: `false`) |

## Response

```json theme={null}
{
  "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

```bash curl theme={null}
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
  }'
```

```python Python theme={null}
import httpx

response = httpx.post(
    "https://api.zenveil.dev/v1/scan/github",
    headers={"X-API-Key": "zvk_live_your_key"},
    json={
        "repository": "owner/repo",
        "token": "ghp_your_github_token",
        "check_cves": True,
    },
)

result = response.json()
print(f"Found {result['finding_count']} findings")

for finding in result["findings"]:
    print(f"[{finding['severity']}] {finding['title']} — {finding['location']['path']}:{finding['location']['line']}")
```

```javascript JavaScript theme={null}
const response = await fetch('https://api.zenveil.dev/v1/scan/github', {
  method: 'POST',
  headers: {
    'X-API-Key': 'zvk_live_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    repository: 'owner/repo',
    token: process.env.GITHUB_TOKEN,
    check_cves: true,
  }),
});

const result = await response.json();
console.log(`Found ${result.finding_count} findings`);

result.findings.forEach(f => {
  console.log(`[${f.severity}] ${f.title} — ${f.location.path}:${f.location.line}`);
});
```

## Error responses

| Status | Error | Cause |
| - | - | - |
| `400` | Bad request | Invalid repository format or missing required fields |
| `400` | Archive download failed | Repository doesn't exist or isn't accessible |
| `403` | Access denied | Private repo requires `--token` with `repo` scope |
| `404` | Repository not found | Repository name is wrong |
| `429` | Rate limit | GitHub API rate limit — add a token to increase limit |
| `500` | Scan failed | Unexpected error — retry |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.