API Reference

Analysis & Scans

Endpoints for triggering scans, retrieving violations, viewing trends, and managing repositories.

Analysis & Scans Endpoints

All endpoints require authentication and are scoped to repositories the user has access to through their organizations.

Repositories

GET /api/repos

List all repositories connected to the current user's organizations.

Request

curl https://api.radar.dev/v1/api/repos \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch("https://api.radar.dev/v1/api/repos", {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const repos = await response.json();

Response 200 OK

[
  {
    "id": "repo_abc123",
    "name": "api",
    "fullName": "acme/api",
    "organizationId": "org_x1y2z3",
    "platform": "github",
    "healthScore": 78,
    "lastScanAt": "2026-03-18T09:15:00.000Z",
    "totalViolations": 12,
    "productionRisk": "MEDIUM"
  },
  {
    "id": "repo_def456",
    "name": "web",
    "fullName": "acme/web",
    "organizationId": "org_x1y2z3",
    "platform": "github",
    "healthScore": 92,
    "lastScanAt": "2026-03-17T16:30:00.000Z",
    "totalViolations": 3,
    "productionRisk": "LOW"
  }
]

GET /api/repos/:id/overview

Get a comprehensive health overview for a repository including violation trends, category breakdown, and production risk assessment.

Request

curl https://api.radar.dev/v1/api/repos/repo_abc123/overview \
  -H "Authorization: Bearer $TOKEN"

Response 200 OK

{
  "healthScore": 78,
  "totalViolations": 12,
  "debtScoreAvg": 11.5,
  "productionRisk": "MEDIUM",
  "categoryBreakdown": {
    "architecture": 2,
    "runtime_risk": 3,
    "performance": 4,
    "reliability": 2,
    "maintainability": 1
  },
  "violationsTrend": [
    { "date": "2026-03-11", "count": 18 },
    { "date": "2026-03-12", "count": 16 },
    { "date": "2026-03-13", "count": 14 },
    { "date": "2026-03-18", "count": 12 }
  ],
  "recentPRs": [
    {
      "prNumber": 142,
      "title": "Add order export endpoint",
      "author": "bob",
      "score": 8,
      "gateResult": "pass",
      "blockingCount": 0,
      "warningCount": 3,
      "date": "2026-03-18T09:15:00.000Z"
    }
  ],
  "topHotspots": [
    {
      "file": "src/orders/orders.service.ts",
      "complexity": 24,
      "churnCount": 15,
      "violationCount": 4,
      "riskScore": 87
    }
  ],
  "categories": {
    "architecture": {
      "count": 2,
      "critical": [
        {
          "file": "src/orders/domain/order.service.ts",
          "line": 5,
          "rule": "layer-boundary-violation",
          "message": "Domain layer imports from infrastructure (@prisma/client)"
        }
      ],
      "warning": []
    },
    "runtime_risk": {
      "count": 3,
      "critical": [
        {
          "file": "src/export/export.controller.ts",
          "line": 22,
          "rule": "sync-fs-in-handler",
          "message": "fs.readFileSync blocks the event loop in request handler"
        }
      ],
      "warning": []
    },
    "performance": {
      "count": 4,
      "critical": [
        {
          "file": "src/events/events.repository.ts",
          "line": 15,
          "rule": "unbounded-find-many",
          "message": "prisma.event.findMany() without pagination on XL table (1M+ rows)",
          "table": "event",
          "volume": "XL"
        }
      ],
      "warning": []
    },
    "reliability": {
      "count": 2,
      "critical": [],
      "warning": []
    },
    "maintainability": {
      "count": 1,
      "hotspots": [
        {
          "file": "src/orders/orders.service.ts",
          "complexity": 24,
          "churn": 15,
          "riskScore": 87
        }
      ]
    }
  }
}

Violations

GET /api/repos/:id/violations

List violations for a repository with filtering and pagination.

Request

curl "https://api.radar.dev/v1/api/repos/repo_abc123/violations?category=performance&severity=critical&page=1&perPage=20" \
  -H "Authorization: Bearer $TOKEN"

const params = new URLSearchParams({
  category: "performance",
  severity: "critical",
  page: "1",
  perPage: "20",
});
const response = await fetch(
  `https://api.radar.dev/v1/api/repos/repo_abc123/violations?${params}`,
  { headers: { Authorization: `Bearer ${accessToken}` } }
);
const { data, total, page, totalPages } = await response.json();

Query Parameters

ParameterTypeDefaultDescription
categorystring--Filter: architecture, runtime_risk, performance, reliability, maintainability
severitystring--Filter: critical, warning, info
modulestring--Filter by module name
pagenumber1Page number
perPagenumber20Items per page

Response 200 OK

{
  "data": [
    {
      "id": "vio_abc123",
      "category": "performance",
      "type": "unbounded-find-many",
      "ruleId": "unbounded-find-many",
      "severity": "critical",
      "source": "deterministic",
      "confidence": "high",
      "file": "src/events/events.repository.ts",
      "line": 15,
      "function": "getAllEvents",
      "message": "prisma.event.findMany() without take/skip on XL table",
      "suggestion": "Add take/skip pagination or a where clause to limit results",
      "debtPoints": 8,
      "gateAction": "block"
    }
  ],
  "total": 4,
  "page": 1,
  "perPage": 20,
  "totalPages": 1
}

GET /api/repos/:id/trends

Get violation and debt score trends over time.

Request

curl "https://api.radar.dev/v1/api/repos/repo_abc123/trends?period=30d" \
  -H "Authorization: Bearer $TOKEN"

Query Parameters

ParameterTypeDefaultDescription
periodstring30dTime period: 7d, 14d, 30d, 60d, 90d

Response 200 OK

{
  "violations": [
    { "date": "2026-02-17", "total": 22, "critical": 8, "warning": 14 },
    { "date": "2026-02-24", "total": 19, "critical": 6, "warning": 13 },
    { "date": "2026-03-03", "total": 16, "critical": 5, "warning": 11 },
    { "date": "2026-03-10", "total": 14, "critical": 4, "warning": 10 },
    { "date": "2026-03-17", "total": 12, "critical": 3, "warning": 9 }
  ],
  "debtScores": [
    { "date": "2026-02-17", "score": 28 },
    { "date": "2026-02-24", "score": 22 },
    { "date": "2026-03-03", "score": 18 },
    { "date": "2026-03-10", "score": 14 },
    { "date": "2026-03-17", "score": 11.5 }
  ],
  "categoryTrends": {
    "architecture": [2, 2, 2, 2, 2],
    "runtime_risk": [5, 4, 4, 3, 3],
    "performance": [8, 7, 5, 5, 4],
    "reliability": [4, 3, 3, 2, 2],
    "maintainability": [3, 3, 2, 2, 1]
  }
}

Hotspots

GET /api/repos/:id/hotspots

Get files ranked by risk score (combination of complexity, churn frequency, and violation density).

Request

curl https://api.radar.dev/v1/api/repos/repo_abc123/hotspots \
  -H "Authorization: Bearer $TOKEN"

Response 200 OK

[
  {
    "file": "src/orders/orders.service.ts",
    "complexity": 24,
    "churnCount": 15,
    "violationCount": 4,
    "riskScore": 87
  },
  {
    "file": "src/events/events.repository.ts",
    "complexity": 12,
    "churnCount": 8,
    "violationCount": 3,
    "riskScore": 65
  }
]

PR History

GET /api/repos/:id/prs

List PR analysis history with gate results.

Request

curl "https://api.radar.dev/v1/api/repos/repo_abc123/prs?page=1&perPage=20" \
  -H "Authorization: Bearer $TOKEN"

Response 200 OK

{
  "data": [
    {
      "prNumber": 142,
      "title": "Add order export endpoint",
      "author": "bob",
      "score": 8,
      "gateResult": "pass",
      "blockingCount": 0,
      "warningCount": 3,
      "date": "2026-03-18T09:15:00.000Z"
    },
    {
      "prNumber": 141,
      "title": "Refactor auth middleware",
      "author": "jane",
      "score": 22,
      "gateResult": "fail",
      "blockingCount": 2,
      "warningCount": 5,
      "date": "2026-03-17T14:22:00.000Z"
    }
  ],
  "total": 87,
  "page": 1,
  "perPage": 20,
  "totalPages": 5
}

Runtime Risks

GET /api/repos/:id/runtime-risks

Get detailed runtime risk analysis for the repository.

curl https://api.radar.dev/v1/api/repos/repo_abc123/runtime-risks \
  -H "Authorization: Bearer $TOKEN"

Policy Management

GET /api/repos/:id/policy

Get the current radar.yml policy configuration for a repository.

curl https://api.radar.dev/v1/api/repos/repo_abc123/policy \
  -H "Authorization: Bearer $TOKEN"

PUT /api/repos/:id/policy

Update the policy via the visual policy editor. Requires Pro plan or above.

curl -X PUT https://api.radar.dev/v1/api/repos/repo_abc123/policy \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stack": { "framework": "nestjs", "orm": "prisma", "language": "TypeScript", "runtime": "node" },
    "architecture": "ddd",
    "layers": [{ "name": "domain", "path": "src/*/domain" }],
    "gates": { "block_merge": [{ "metric": "debt_delta_score", "operator": ">", "value": 15 }], "warn": [] }
  }'

POST /api/repos/:id/policy/preview

Preview what a policy change would detect without persisting it.

curl -X POST https://api.radar.dev/v1/api/repos/repo_abc123/policy/preview \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "stack": { "framework": "nestjs", "orm": "prisma" } }'

Architecture Graph

GET /api/repos/:id/architecture-graph

Get the D3-compatible architecture graph data with nodes, edges, modules, and layers. Requires Pro plan or above.

curl https://api.radar.dev/v1/api/repos/repo_abc123/architecture-graph \
  -H "Authorization: Bearer $TOKEN"

Response 200 OK

{
  "nodes": [
    {
      "id": "src/orders/orders.controller.ts",
      "label": "orders.controller",
      "module": "orders",
      "layer": "controller",
      "type": "file",
      "violations": 0,
      "complexity": 8,
      "linesOfCode": 120,
      "isHotspot": false
    }
  ],
  "edges": [
    {
      "source": "src/orders/orders.controller.ts",
      "target": "src/orders/orders.service.ts",
      "type": "import",
      "isViolation": false,
      "violationType": null,
      "message": null
    }
  ],
  "modules": [
    { "name": "orders", "path": "src/orders", "nodeCount": 8, "violations": 2 }
  ],
  "layers": [
    { "name": "controller", "color": "#4CAF50" },
    { "name": "service", "color": "#2196F3" },
    { "name": "repository", "color": "#FF9800" }
  ],
  "stats": {
    "totalNodes": 45,
    "totalEdges": 78,
    "violationEdges": 3,
    "circularEdges": 1,
    "modules": 6,
    "layers": 4
  }
}

Manual Analysis

POST /api/repos/:id/analyze

Trigger a manual analysis run outside of the PR workflow.

curl -X POST https://api.radar.dev/v1/api/repos/repo_abc123/analyze \
  -H "Authorization: Bearer $TOKEN"

Response 200 OK

{
  "runId": "run_xyz789",
  "status": "queued",
  "message": "Analysis queued successfully"
}

First Scan

GET /api/repos/:id/first-scan

Get the baseline first-scan results for a repository. This is generated when a repo is first connected.

curl https://api.radar.dev/v1/api/repos/repo_abc123/first-scan \
  -H "Authorization: Bearer $TOKEN"

Rule Packs

GET /api/packs

List available rule packs. Optionally filter by search query or framework.

# List all packs
curl https://api.radar.dev/v1/api/packs \
  -H "Authorization: Bearer $TOKEN"

# Search packs
curl "https://api.radar.dev/v1/api/packs?q=nestjs" \
  -H "Authorization: Bearer $TOKEN"

# Filter by framework
curl "https://api.radar.dev/v1/api/packs?framework=nestjs" \
  -H "Authorization: Bearer $TOKEN"

GET /api/packs/:name

Get details for a specific rule pack.

curl https://api.radar.dev/v1/api/packs/nestjs-strict \
  -H "Authorization: Bearer $TOKEN"

POST /api/repos/:id/apply-pack

Apply a rule pack to a repository. Requires Pro plan or above.

curl -X POST https://api.radar.dev/v1/api/repos/repo_abc123/apply-pack \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "packName": "nestjs-strict" }'
Previous← Billing & CreditsNextWebhook Events →
Technical Debt Radar Documentation