API docs

JSON API v1.

Browse the public registry programmatically. Read all skills + CLAUDE.md. Submit your own. PAT auth for writes, no signup for reads.

Quick start

Try it in one line.

$ curl 'https://versuz.dev/api/v1/skills?limit=3' | jq '.items[].name'

Auth (writes only)

GitHub PAT.

Reads are public. Writes (submit) require a GitHub Personal Access Token sent in the request body. Versuz verifies it via GitHub's /user endpoint, never stores the raw token. Use the public_repo scope, no more.

Endpoints

GET/api/v1/skills

List skills

Paginated list of indexed SKILL.md items. Default 50 per page, max 100.

Parameters

Name	Type	Default	Description
`page`	int	1	Page number, 1-indexed
`limit`	int	50	Items per page (max 100)
`category`	enum	—	document, sql, data, web, shell, code
`tier`	enum	—	free, premium, featured
`min_verification`	int	0	Min verification level (0-4)
`q`	string	—	Search across name + slug + description
`sort`	enum	prior	prior, stars, recent, name

Example

curl 'https://versuz.dev/api/v1/skills?category=document&limit=10&sort=stars'

Response (200)

{
  "api_version": "v1",
  "kind": "skill",
  "page": 1,
  "limit": 10,
  "total": 487,
  "items": [
    {
      "slug": "pdf-generator",
      "name": "PDF Generator",
      "description": "Generate styled PDFs from markdown with a single command.",
      "category": "document",
      "tier": "free",
      "price_usd": null,
      "verification_level": 2,
      "stars": 1247,
      "forks": 89,
      "topics": ["pdf", "markdown"],
      "license": "MIT",
      "pushed_at": "2026-05-10T14:23:00Z",
      "github_url": "https://github.com/example/pdf-generator",
      "skill_type": "bundled",
      "prior": 1843.2
    }
  ]
}

GET/api/v1/skills/{slug}

Get one skill

Full metadata of a single skill, including bench scores and judge axes when available.

Parameters

Name	Type	Default	Description
`slug`	string	—	Skill slug (path param)

Example

curl 'https://versuz.dev/api/v1/skills/pdf-generator'

Response (200)

{
  "api_version": "v1",
  "kind": "skill",
  "item": {
    "slug": "pdf-generator",
    "name": "PDF Generator",
    "description": "...",
    "category": "document",
    "tier": "free",
    "verification_level": 2,
    "stars": 1247,
    "license": "MIT",
    "github_url": "https://github.com/example/pdf-generator",
    "bench_score": 78.4,
    "task_count": 5,
    "axes": {
      "instruction_following": 82.1,
      "correctness": 75.3,
      "completeness": 80.0,
      "usefulness": 79.5,
      "safety": 72.0
    }
  }
}

GET/api/v1/skills/{slug}/content

Get raw SKILL.md content

Returns the raw markdown body of a skill. Free items are open. Premium items return 402 Payment Required with a buy_url.

Parameters

Name	Type	Default	Description
`slug`	string	—	Skill slug (path param)

Example

curl 'https://versuz.dev/api/v1/skills/pdf-generator/content'

Response (200)

{
  "api_version": "v1",
  "kind": "skill",
  "slug": "pdf-generator",
  "name": "PDF Generator",
  "description": "...",
  "content": "---\nname: pdf-generator\n...\n---\n\n# PDF Generator\n\n...",
  "bundle_files": [
    { "name": "scripts/render.py", "type": "file", "size": 4012 }
  ],
  "github_url": "https://github.com/example/pdf-generator"
}

Premium items return HTTP 402 with { error, slug, tier, price_usd, buy_url }.

GET/api/v1/claude-md

List CLAUDE.md

Paginated list of indexed CLAUDE.md items. Same param shape as /skills.

Parameters

Name	Type	Default	Description
`page`	int	1	Page number
`limit`	int	50	Items per page (max 100)
`category`	enum	—	nextjs, react, python-data, backend-api, mobile, devops, ml-training, generic
`tier`	enum	—	free, premium, featured
`q`	string	—	Search across slug + description
`sort`	enum	stars	stars, recent, name

Example

curl 'https://versuz.dev/api/v1/claude-md?category=nextjs&limit=5'

Response (200)

{
  "api_version": "v1",
  "kind": "claude_md",
  "page": 1,
  "limit": 5,
  "total": 312,
  "items": [ /* ... shape similar to skills, with project_category instead of category */ ]
}

GET/api/v1/claude-md/{slug}

Get one CLAUDE.md

Full metadata of a single CLAUDE.md file.

Parameters

Name	Type	Default	Description
`slug`	string	—	CLAUDE.md slug

Example

curl 'https://versuz.dev/api/v1/claude-md/owner-repo'

Response (200)

{ "api_version": "v1", "kind": "claude_md", "item": { /* ... */ } }

GET/api/v1/claude-md/{slug}/content

Get raw CLAUDE.md content

Returns the raw markdown body. Same 402 behavior on premium items.

Parameters

Name	Type	Default	Description
`slug`	string	—	CLAUDE.md slug

Example

curl 'https://versuz.dev/api/v1/claude-md/owner-repo/content'

Response (200)

{
  "api_version": "v1",
  "kind": "claude_md",
  "slug": "owner-repo",
  "description": "...",
  "project_category": "nextjs",
  "content": "# Project context\n...",
  "github_url": "https://github.com/owner/repo"
}

POST/api/v1/auth/whoami

Whoami (PAT verification)

Verify a GitHub Personal Access Token and return the authenticated user. Used by the CLI for login.

AuthPAT in body. We hit GitHub's /user endpoint to verify, never store the raw token.

Parameters

Name	Type	Default	Description
`token`	string	—	GitHub PAT, in request body { token: 'ghp_...' }

Example

curl -X POST 'https://versuz.dev/api/v1/auth/whoami' \
  -H 'content-type: application/json' \
  -d '{"token": "ghp_yourtoken"}'

Response (200)

{
  "ok": true,
  "github_user_id": 12345678,
  "login": "octocat",
  "name": "The Octocat"
}

POST/api/v1/submit

Submit a SKILL.md or CLAUDE.md

Submit a public GitHub URL to the registry. Requires PAT auth + ownership of the repo (or org membership). Free tier only via API.

AuthGitHub PAT required. 8-layer anti-spam : auth verified, ownership re-checked, rate limit 5/h/user, 24h URL dedup, strict regex, 200 KB size cap, free tier only via API.

Parameters

Name	Type	Default	Description
`token`	string	—	GitHub PAT for auth + ownership check
`url`	string	—	GitHub URL pointing to a SKILL.md or CLAUDE.md file

Example

curl -X POST 'https://versuz.dev/api/v1/submit' \
  -H 'content-type: application/json' \
  -d '{
    "token": "ghp_yourtoken",
    "url": "https://github.com/you/your-repo/blob/main/SKILL.md"
  }'

Response (200)

{
  "ok": true,
  "kind": "skill",
  "slug": "your-skill",
  "action": "created",
  "url": "https://versuz.dev/skills/your-skill"
}

Returns 401 (auth), 403 (ownership), 409 (duplicate), 413 (size), 429 (rate limit), 422 (invalid URL/content).

Rate limits

GET /api/v1/*Fair useNo hard rate limit on read endpoints. Don't hammer (>10 req/s sustained will get blocked at the edge).

POST /api/v1/submit5 per hour per GitHub userTracked in cli_submissions table by github_user_id. Counts both success and rejected submissions.

POST /api/v1/auth/whoamiFair useEach call hits GitHub /user — be reasonable. Cache the result client-side after first verification.

Errors

Errors return JSON with { error: string } and standard HTTP status codes. 402 for premium gating includes a buy_url. 429 for rate-limited submissions includes retry_after.

CLI + MCP

Most use cases are easier via npx versuz (interactive CLI) or claude mcp add versuz npx -y @versuz/mcp (inline in Claude Code). See about.

Stability

v1 is the only public API. Breaking changes go through a v2 path, announced 30 days in advance on this page + RSS feed at /feed.

Issues / feedback

Report bugs on GitHub issues ↗. API questions : contact@flukxstudio.fr.