DEVELOPERS

API Reference

3 endpoints, JSON responses, no authentication required.

Base URL https://clawsafe.dev

POST /api/scan

Submit an AI skill for security scanning. Supports both URL and file upload flows.

Method 1: Scan by URL

curl -X POST https://clawsafe.dev/api/scan \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/user/skill-repo"}'

Method 2: Upload File

curl -X POST https://clawsafe.dev/api/scan \
  -F "[email protected]"

Response

{
  "verdict": "Malicious",
  "verdictLevel": "malicious",
  "riskScore": { "score": 85, "breakdown": [...] },
  "summary": "Reverse shell payload detected...",
  "findings": [...],
  "extraction": { "iocs": [...], "files": [...] },
  "reportId": "vtKznl4"
}

Parameters

Parameter	Type	Description
`url`	string	GitHub / ClawHub / direct .zip link
`file`	file	ZIP or TAR.GZ file, max 10MB
`force`	boolean	Skip cache and force a fresh scan

GET /api/report/:id

Fetch the full JSON report for a scan. Supports both short IDs and full content hashes.

Request

curl https://clawsafe.dev/api/report/vtKznl4

Response

{
  "data": {
    "id": "vtKznl4",
    "type": "scan-report",
    "attributes": {
      "verdict": "Malicious",
      "verdictLevel": "malicious",
      "riskScore": { "score": 100 },
      "findings": [...],
      "extraction": { ... }
    }
  }
}

GET /api/stats

Fetch aggregate platform statistics.

Request

curl https://clawsafe.dev/api/stats

Response

{
  "data": {
    "totalScans": 18,
    "maliciousBlocked": 7,
    "byVerdict": [
      { "verdict_level": "malicious", "count": 7 },
      { "verdict_level": "trusted", "count": 11 }
    ],
    "recentScans": [
      {
        "id": "vtKznl4",
        "skill_name": "math-calculator",
        "verdict_level": "malicious",
        "trust_score": 0,
        "created_at": 1775147958361
      }
    ]
  }
}