API Reference

Programmatic access to governance scans, rules, and webhooks. Authenticate with an API key generated in Settings > API Keys.

v1.0.0https://api.govnu.dev/v1

Authentication

All API requests require a Bearer token. Generate an API key from your Settings > API Keys page.

bash

curl https://api.govnu.dev/v1/scans \
  -H "Authorization: Bearer gn_live_your_api_key_here"

Your API Key

Enter your API key to enable the “Try it” console on each endpoint below. Your key is stored only in your browser.

Rate Limits

API rate limits showing requests per minute and concurrent scans by tier
Tier	Requests / min	Concurrent scans
Starter	60	1
Pro	300	5
Enterprise	Custom	Custom

Error Format

Errors follow a consistent envelope with a machine-readable code and human-readable message.

json

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}

Scans

Trigger and monitor governance scans across your repositories.

Rules

Manage built-in and custom governance rules.

Webhooks

Webhook Payload Schemas

Every webhook delivery is signed with your endpoint's secret using HMAC-SHA256. Verify the X-GovNu-Signature header before processing.

Envelope Format

json

{
  "id": "evt_01HXA2B3C4",
  "event": "scan.completed",
  "timestamp": "2026-02-26T10:32:15Z",
  "organizationId": "org_abc123",
  "data": {
    "...": "event-specific payload"
  }
}

Event Types

scan.startedFired when a governance scan is queued and begins processing.

json

{
  "id": "evt_01HXA2B3C4",
  "event": "scan.started",
  "timestamp": "2026-02-26T10:30:00Z",
  "organizationId": "org_abc123",
  "data": {
    "scanId": "scan_01HX9K3M",
    "repositoryId": "repo_abc123",
    "repositoryName": "acme/web-app",
    "branch": "main",
    "mode": "scan-remediate",
    "triggeredBy": "api"
  }
}

scan.completedFired when a scan finishes successfully with results available.

json

{
  "id": "evt_01HXA2B3C5",
  "event": "scan.completed",
  "timestamp": "2026-02-26T10:32:15Z",
  "organizationId": "org_abc123",
  "data": {
    "scanId": "scan_01HX9K3M",
    "repositoryId": "repo_abc123",
    "repositoryName": "acme/web-app",
    "branch": "main",
    "score": 87.5,
    "totalViolations": 12,
    "criticalViolations": 2,
    "highViolations": 4,
    "mediumViolations": 3,
    "lowViolations": 3,
    "durationMs": 135000
  }
}

scan.failedFired when a scan encounters an unrecoverable error.

json

{
  "id": "evt_01HXA2B3C6",
  "event": "scan.failed",
  "timestamp": "2026-02-26T10:31:00Z",
  "organizationId": "org_abc123",
  "data": {
    "scanId": "scan_01HX9K3M",
    "repositoryId": "repo_abc123",
    "repositoryName": "acme/web-app",
    "branch": "main",
    "errorCode": "CLONE_FAILED",
    "errorMessage": "Repository access denied. Check GitHub permissions."
  }
}

rule.violatedFired for each governance rule violation detected during a scan.

json

{
  "id": "evt_01HXA2B3C7",
  "event": "rule.violated",
  "timestamp": "2026-02-26T10:32:15Z",
  "organizationId": "org_abc123",
  "data": {
    "scanId": "scan_01HX9K3M",
    "violationId": "viol_01HX9K3N",
    "ruleId": "rule_a1b2c3",
    "ruleName": "require-error-boundaries",
    "severity": "high",
    "filePath": "src/app/dashboard/page.tsx",
    "line": 42,
    "message": "Missing error boundary for data-fetching component",
    "suggestion": "Wrap component with ErrorBoundary from @/components/ui/error-state"
  }
}

rule.createdFired when a new custom governance rule is created.

json

{
  "id": "evt_01HXA2B3C8",
  "event": "rule.created",
  "timestamp": "2026-02-26T14:00:00Z",
  "organizationId": "org_abc123",
  "data": {
    "ruleId": "rule_x1y2z3",
    "name": "require-logging-adapter",
    "domain": "observability",
    "severity": "medium",
    "createdBy": "user_def456"
  }
}

rule.updatedFired when an existing custom rule is modified.

json

{
  "id": "evt_01HXA2B3C9",
  "event": "rule.updated",
  "timestamp": "2026-02-26T15:30:00Z",
  "organizationId": "org_abc123",
  "data": {
    "ruleId": "rule_x1y2z3",
    "name": "require-logging-adapter",
    "changes": [
      "severity",
      "description"
    ],
    "updatedBy": "user_def456"
  }
}

Agents

Dispatch code-generation tasks to external agents and monitor their progress. Requires the enable_agent_gateway feature flag and an API key with agents:write or agents:read scope.

Agent dispatch limits showing dispatches per month and racing by tier
Tier	Dispatches / month	Racing
Starter	0 (validate only)	No
Pro	10	No
Enterprise	Unlimited	Yes

Governance

Access governance intelligence directly. Validate code, browse the skill catalog, and fetch task-relevant governance context. Available on all tiers.

SDK Samples

Ready-to-use code for the most common API workflows. Available in cURL, Node.js, and Python.

Trigger a scan and poll for results

Start a governance scan on a repository and poll until it completes.

# Trigger the scan
SCAN=$(curl -s -X POST https://api.govnu.dev/v1/scans \
  -H "Authorization: Bearer $GOVNU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repositoryId": "repo_abc123", "branch": "main"}')

SCAN_ID=$(echo $SCAN | jq -r '.id')

# Poll until complete
while true; do
  STATUS=$(curl -s https://api.govnu.dev/v1/scans/$SCAN_ID \
    -H "Authorization: Bearer $GOVNU_API_KEY" | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
  sleep 5
done

# Fetch violations
curl -s https://api.govnu.dev/v1/scans/$SCAN_ID/violations \
  -H "Authorization: Bearer $GOVNU_API_KEY" | jq .

List all violations from recent scans

Retrieve completed scans and aggregate violations by severity.

# List completed scans
curl -s "https://api.govnu.dev/v1/scans?status=completed&pageSize=10" \
  -H "Authorization: Bearer $GOVNU_API_KEY" | jq '.data[] | {id, score, totalViolations}'

Register a webhook for scan completions

Set up a webhook to receive real-time notifications when scans finish.

# Register webhook
curl -s -X POST https://api.govnu.dev/v1/webhooks \
  -H "Authorization: Bearer $GOVNU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/hooks/govnu",
    "events": ["scan.completed", "scan.failed"]
  }' | jq .

# Save the "secret" field — you need it to verify payloads

Dispatch an agent task and poll for completion

Send a code-generation task to an external agent and wait for results.

# Dispatch the task
TASK=$(curl -s -X POST https://api.govnu.dev/v1/agents/dispatch \
  -H "Authorization: Bearer $GOVNU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "AQ12",
    "planId": "plan-uuid-here",
    "orgId": "org-uuid-here",
    "adapterType": "devin",
    "requirements": "Create a settings page for agent integrations",
    "blastRadius": ["src/app/settings/agent-integrations/"]
  }')

TASK_ID=$(echo $TASK | jq -r '.data.taskId')

# Poll until terminal state
while true; do
  RESULT=$(curl -s https://api.govnu.dev/v1/agents/tasks/$TASK_ID \
    -H "Authorization: Bearer $GOVNU_API_KEY")
  STATUS=$(echo $RESULT | jq -r '.data.status')
  echo "Status: $STATUS"
  case $STATUS in completed|failed|cancelled|timed_out) break;; esac
  sleep 10
done

Validate code against governance rules

Submit a code snippet for governance validation. Available on all tiers.

curl -s -X POST https://api.govnu.dev/v1/governance/validate \
  -H "Authorization: Bearer $GOVNU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "console.log(\"hello\");\nconst x = 1;",
    "filePath": "src/lib/utils.ts",
    "language": "typescript"
  }' | jq '.data.summary'