← back to skillsmith

API Reference

Base URL: https://skillsmith.ch (mirrored at https://skillsmith-web.vercel.app). All responses are JSON. No SDK needed -- plain HTTP.

Pricing tiers

All paid tiers are activated by sending USDC (SPL token, Solana mainnet, mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v) to 2esJogvKTYDuxZaB9PEuEaHvz4U6TuQnTx3pkLcdH34N, then submitting the finalized transaction signature. Pay-as-you-go always requires an existing account (api_key) and is additive to whatever tier you're on -- it never replaces the free daily quota, it tops it up. No card, no subscription billing surprises -- Pro/Premium simply expire after 30 days.

"Database" here means the Safe Skills Database -- looking up a hash's verdict (/api/lookup), browsing clean skills (/api/registry), or fetching a published skill's actual, usable content (/api/skill). All three share the same daily lookup quota.

Authentication

Every scan/lookup call needs an api_key, either as a JSON body field, a query param (GET requests), or an Authorization: Bearer <key> header. Get one from POST /api/signup or by signing in with GitHub (/api/auth/github/start), which recovers the same key/quota on any device you sign in from again.

Endpoints

POST/api/signup

Create an anonymous account. No email/password.

curl -X POST https://skillsmith.ch/api/signup

{"api_key": "sk_...", "free_daily_limit": 5, "pro_daily_limit": 100, "pro_price_usdc": 5.0, "pro_duration_days": 30}

GET/api/signup?api_key=...

Check your account's current tier and quota usage.

curl "https://skillsmith.ch/api/signup?api_key=sk_..."

{"tier": "free", "limit": 5, "used": 2, "remaining": 3, "pro_price_usdc": 5.0, "pro_duration_days": 30}

GET/api/auth/github/start

Redirects to GitHub OAuth. On success, redirects back to /#key=sk_... with your (possibly pre-existing) account key.

POST/api/scan

Lint + security-scan one SKILL.md. Consumes 1 unit of your scan quota.

curl -X POST https://skillsmith.ch/api/scan \
  -H "Content-Type: application/json" \
  -d '{"api_key":"sk_...","text":"---\nname: x\ndescription: y\n---\n\nbody"}'

# or scan a GitHub link instead of pasting text:
curl -X POST https://skillsmith.ch/api/scan \
  -d '{"api_key":"sk_...","url":"https://github.com/owner/repo/blob/main/SKILL.md"}'

Response includes parse_ok, lint_ok, lint_issues[], findings[], risk_score, risk_level, security_score (0-100), sha256, scan_history, disclaimer, and quota.

POST/api/scan_pro

Two things, based on what you send:

1. Activate Pro or Premium:

curl -X POST https://skillsmith.ch/api/scan_pro \
  -d '{"api_key":"sk_...","activate_payment_signature":"<tx>"}'
# add "tier":"premium" (and send $10 instead of $5) for the unlimited tier

2. Batch-scan up to 25 files (once Pro/Premium is active; consumes 1 unit of your scan quota per call, not per file):

curl -X POST https://skillsmith.ch/api/scan_pro \
  -d '{"api_key":"sk_...","files":[{"name":"a/SKILL.md","text":"..."},{"name":"b/SKILL.md","text":"..."}]}'

GET/api/lookup?sha256=...&api_key=...

VirusTotal-style hash lookup: has this exact file been scanned before? Requires sign-in; consumes 1 unit of your daily DB-lookup quota (separate from the scan quota -- see pricing table above).

curl "https://skillsmith.ch/api/lookup?sha256=4807c1a3de60...&api_key=sk_..."

{"found": true, "record": {"sha256": "...", "name": "date-formatter", "seen_count": 3, "risk_level": "clean", ...}, "quota": {...}}

GET/api/registry?api_key=...&limit=50

Browse the public Safe Skills Database: skills that scanned clean + lint-ok, newest first. Each entry has a has_content flag -- true if the submitter published the actual content (see below). Also consumes 1 unit of your DB-lookup quota. Explicitly an automated-heuristic result, not a manual audit.

curl "https://skillsmith.ch/api/registry?api_key=sk_..."

GET/api/skill?sha256=...&api_key=...

Fetch the actual, usable SKILL.md content for a hash -- the "use the skill" endpoint, distinct from /api/lookup (verdict/metadata only). Only works if the submitter explicitly published it by ticking "Publish to Safe Skills DB" on a clean scan (POST /api/scan with "publish": true). Returns 404 if not published. Consumes 1 unit of your DB-lookup quota.

curl "https://skillsmith.ch/api/skill?sha256=4807c1a3de60...&api_key=sk_..."

{"sha256": "...", "text": "---\nname: date-formatter\n...", "quota": {...}}

POST/api/buy_credit (pay-as-you-go, additive)

Buy one extra scan or lookup without a Pro/Premium subscription. Always requires an existing account and on-chain USDC payment; tops up whatever tier you're already on, never replaces it.

curl -X POST https://skillsmith.ch/api/buy_credit \
  -d '{"api_key":"sk_...","payment_signature":"<tx>","kind":"scan"}'    # $0.02, +1 scan
curl -X POST https://skillsmith.ch/api/buy_credit \
  -d '{"api_key":"sk_...","payment_signature":"<tx>","kind":"lookup"}'  # $0.01, +1 lookup

Errors

Source

Full implementation: github.com/Larslllllll/skillsmith-web (this web app) and github.com/Larslllllll/skillsmith (the underlying CLI/library and detection engine, also usable standalone or as a GitHub Action).