GET /scan/:id and /skill/:name

Two read endpoints, both public, both unauthenticated. The first fetches a specific scan by ID; the second fetches the most-recent completed scan for a given skill name (from SKILL.md frontmatter).

GET /scan/:id

Fetches the scan record. Use this to poll for completion after a POST /scan.

curl https://api.skillox.io/scan/sk_pprsxxv0typ34oq5x2ufzd4q

Response

200 OK

{
  "scanId": "sk_pprsxxv0typ34oq5x2ufzd4q",
  "url": "https://github.com/skillox-examples/safe-formatter/blob/main/SKILL.md",
  "sourceRepo": "skillox-examples/safe-formatter",
  "skillName": "safe-formatter",
  "skillVersion": "1.2.0",
  "status": "completed",
  "grade": "A",
  "score": 95,
  "findings": [],
  "scanDurationMs": 5,
  "errorMessage": null,
  "createdAt": "2026-05-21T19:55:40.321Z",
  "completedAt": "2026-05-21T20:55:12.319Z"
}

• status — pending → running → completed | failed
• findings — array of Finding objects (severity, title, line, context, cwe). See Finding shape.
• skillName + skillVersion — parsed from frontmatter. May be null when no frontmatter is present.
• errorMessage — populated when status="failed" (fetch error, timeout, etc.).

GET /skill/:name

Returns the latest completed scan for a given skill name plus a totalScans aggregate. Used by the Skill Report Card pages at /c/[skillName].

curl https://api.skillox.io/skill/safe-formatter

Response

200 OK

{
  "skillName": "safe-formatter",
  "totalScans": 1,
  "latest": {
    "scanId": "sample-grade-a",
    "url": "https://github.com/skillox-examples/safe-formatter/blob/main/SKILL.md",
    "sourceRepo": "skillox-examples/safe-formatter",
    "skillName": "safe-formatter",
    "skillVersion": "1.2.0",
    "status": "completed",
    "grade": "A",
    "score": 95,
    "findings": [],
    "scanDurationMs": 5,
    "createdAt": "2026-05-21T19:55:40.321Z",
    "completedAt": "2026-05-21T20:55:12.319Z"
  }
}

Returns 404 not_found if no completed scan exists for that name. The lookup is exact-match on the frontmatter name field.