中文 EN
Start Review
API Reference

The API is not here to “run a scan”.
It is here to inject a trust decision into your system.

The ClawSafe API matters because it lets your workflow receive an install recommendation before merge, sync, enablement, or audit actions happen. The output is not just JSON. It is a decision object with evidence attached.

Base URL https://clawsafe.dev

Authentication

Authenticate API requests using a Bearer token. Create a key in Account → API Keys. Keys are in sk_xxx… format and are shown in full only once at creation — store them securely.

Example request 
curl -X POST https://clawsafe.dev/api/scan \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://github.com/user/skill-repo","locale":"en"}'

The response contract that matters most

verdictLevel

Install recommendation tier: trusted / low_risk / suspicious / high_risk / malicious.

riskScore.score

Numeric risk score for sorting and thresholding, but not for standalone use.

findings

Structured findings suitable for surfacing primary trust-breaking reasons.

capabilityMap

Declared-versus-actual capability map used to detect drift and violations.

extraction

Static evidence including artifacts, file tree, language mix, and sensitive files.

Core endpoints

POST /api/scan

Submit a target for review. Supports URL input or file upload.

Request 
curl -X POST https://clawsafe.dev/api/scan \
  -H "Content-Type: application/json" \
  -d '{"url":"https://github.com/user/skill-repo","locale":"en"}'
Response 
{
  "reportId": "vtKznl4",
  "id": "vtKznl4",
  "status": "completed",
  "verdictLevel": "high_risk",
  "riskScore": { "score": 82, "breakdown": [...] },
  "findings": [...],
  "capabilityMap": [...],
  "extraction": {...},
  "report_url": "https://clawsafe.dev/report/vtKznl4"
}
GET /api/report/:id

Fetch the full JSON for a report that already exists.

Request 
curl https://clawsafe.dev/api/report/vtKznl4
Response 
{
  "data": {
    "id": "vtKznl4",
    "type": "scan-report",
    "attributes": {
      "verdictLevel": "high_risk",
      "riskScore": { "score": 82 },
      "findings": [...],
      "capabilityMap": [...],
      "extraction": {...}
    }
  }
}
GET /api/stats

Read platform-level statistics for dashboards or external views.

Request 
curl https://clawsafe.dev/api/stats
Response 
{
  "data": {
    "totalScans": 18,
    "maliciousBlocked": 7,
    "byVerdict": [...],
    "recentScans": [...]
  }
}

Recommended usage patterns

Pre-install gate

Call /api/scan before importing a skill, syncing a registry, or allowing a user to enable it.

CI risk gate

Use verdictLevel or riskScore for merge blocking, but keep findings as the human review basis.

Audit replay

Persist reportId so tickets, approval flows, or incidents can reference the same report later.

Rate limits

POST /api/scan is rate-limited by account tier: Free 5/day, Starter 50/day, Pro unlimited (fair use). Unauthenticated requests are limited to 1/hour per IP. GET queries do not require authentication. Every response includes X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset headers. When using an API Key, these headers reflect your API-specific quota (Starter: 10/day, Pro: 1,000/month) rather than your overall scan quota.

CLI Tool

Use the clawsafe CLI to scan from your terminal. Supports URL input and local file upload, with human-readable reports or raw JSON output. Integrate into CI/CD pipelines using exit codes as pipeline gates (0=low risk, 1=suspicious, 2=high risk, 3=malicious, 99=error).

Install 
# Option A: run directly without installing
node clawsafe.js scan <url> --key sk_xxx

# Option B: install globally via npm
npm install -g clawsafe
clawsafe scan <url> --key sk_xxx
Examples 
# Scan a GitHub repository
clawsafe scan https://github.com/user/my-skill --key sk_xxx

# Scan a local archive
clawsafe scan --file ./skill.zip --key sk_xxx

# CI/CD gate — block if score >= 70
clawsafe scan "$SKILL_URL" --key "$CLAWSAFE_KEY" --threshold 70 || exit 1

# Output raw JSON for scripting
clawsafe scan <url> --json | jq '.verdictLevel'

Plans & quotas

PlanPriceScan quotaReport retentionAPI callsExtras
Free$05 / day7 days––
Starter$1.98/mo50 / day90 days10 / dayPrivate reports
Pro$8.98/moUnlimited (fair use)Forever1,000 / monthPrivate reports + Monitors
View Integration Patterns Scan Online