POST /scan

Submit a SKILL.md URL for scanning. Returns immediately with a scanId you can poll via GET /scan/:id. The actual scan runs asynchronously in the worker.

Request

POST https://api.skillox.io/scan
Content-Type: application/json

{
  "url": "https://raw.githubusercontent.com/foo/bar/main/SKILL.md",
  "turnstileToken": "<cloudflare turnstile token>"
}

Fields

• url — string, required. Must be an HTTP(S) URL. github.com/.../blob/... URLs are auto-converted to raw.githubusercontent.com.
• turnstileToken — string, required. From the browser's Turnstile challenge. Use Cloudflare's always-pass dev token in development.

Response · 200 OK

200 OK

{
  "scanId": "sk_pprsxxv0typ34oq5x2ufzd4q",
  "resultUrl": "https://skillox.io/r/sk_pprsxxv0typ34oq5x2ufzd4q",
  "remaining": 9
}

• scanId — the cuid2-prefixed scan ID
• resultUrl — the public URL where the report will be live once the worker finishes
• remaining — how many scans you have left in the current 24h window

Errors

• 400 invalid_request — the URL didn't parse, wasn't HTTP(S), or didn't start with http
• 403 turnstile_failed — Turnstile token didn't validate against the server-side secret
• 429 rate_limited — you hit the 10-scans-per-24h cap. The retryAfterSec field is the seconds until reset.
• 500 turnstile_misconfigured — the server is missing the Turnstile secret. Operator error, not your problem.

429 response example

429 Too Many Requests
Retry-After: 43200

{
  "error": "rate_limited",
  "retryAfterSec": 43200
}