API Reference

The Repohelm REST API lets you manage repositories, trigger scans, query findings, and update policies programmatically. All requests require authentication via bearer token.

Authentication

Include your API token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Generate tokens from your Repohelm dashboard under Settings > API Tokens.

Base URL

https://api.repohelm.com

GET /v1/repos

List all repositories connected to your Repohelm account.

GET /v1/repos
Authorization: Bearer YOUR_TOKEN

Response 200:
{
  "repos": [
    {
      "id": "repo_abc123",
      "name": "acme-corp/backend-api",
      "provider": "github",
      "last_scan": "2026-05-28T14:32:00Z",
      "finding_count": 3
    }
  ],
  "total": 12
}

POST /v1/scans

Trigger a new dependency scan for one or more repositories.

POST /v1/scans
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "repo_ids": ["repo_abc123"]
}

Response 202:
{
  "scan_id": "scan_xyz789",
  "status": "queued",
  "estimated_ms": 240000
}

GET /v1/scans/{id}

Get the status and results of a scan.

GET /v1/scans/scan_xyz789
Authorization: Bearer YOUR_TOKEN

Response 200:
{
  "scan_id": "scan_xyz789",
  "status": "completed",
  "started_at": "2026-05-28T14:32:00Z",
  "completed_at": "2026-05-28T14:36:12Z",
  "findings_count": 3,
  "prs_opened": 3
}

GET /v1/findings

List findings from the most recent scan across all connected repositories.

GET /v1/findings?severity=CRITICAL&repo_id=repo_abc123
Authorization: Bearer YOUR_TOKEN

Response 200:
{
  "findings": [
    {
      "id": "finding_001",
      "cve": "CVE-2021-23337",
      "severity": "CRITICAL",
      "package": "lodash",
      "installed_version": "4.17.20",
      "fix_version": "4.17.21",
      "reachable": true,
      "pr_url": "https://github.com/acme-corp/backend-api/pull/247"
    }
  ]
}

PUT /v1/policy

Update your organization's governance policy.

PUT /v1/policy
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "severity_threshold": "CRITICAL",
  "auto_merge": {
    "enabled": true,
    "max_severity": "MEDIUM"
  },
  "licenses": {
    "deny": ["GPL-3.0", "AGPL-3.0"]
  }
}

Response 200:
{
  "updated": true,
  "effective_at": "2026-05-28T15:00:00Z"
}

Rate limits

The API is rate-limited to 100 requests per minute per token. Scan triggers count as 1 request regardless of the number of repositories. Exceeding the limit returns a 429 Too Many Requests response.

Errors

All errors follow a consistent format:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API token"
  }
}