API Reference

All endpoints use JSON. Auth via session cookie (browser) or API key (CI/CD).

Authentication

For programmatic access, generate an API key from your dashboard and pass it as a Bearer token:

Authorization: Bearer sk_...

POST /api/publish

Create a new skill listing. Auth: API key.

curl -X POST https://skillshope.com/api/publish \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"My Skill","description":"...","category":"productivity"}'

Returns: 201 with skill object. Rate limit: 5/min.

GET /api/registry/<slug>

Look up skill metadata. No auth required. Used by the CLI.

curl https://skillshope.com/api/registry/pdf-processing

Returns: skill metadata, files, versions, dependencies, formats.

GET /api/deliver/<skillId>

Download skill content. Free skills: open. Paid skills: token or session required.

# Free skill
curl https://skillshope.com/api/deliver/<id>

# Paid skill with token
curl https://skillshope.com/api/deliver/<id>?token=<download-token>

Returns: { files: [{ filename, content }] }. Increments download count.

POST /api/api-keys

Create an API key. Auth: session.

curl -X POST https://skillshope.com/api/api-keys \
  -H "Content-Type: application/json" \
  -d '{"name":"github-actions"}'

Returns: { key: 'sk_...', name }. The key is shown once and cannot be retrieved again.

POST /api/skills/<id>/versions

Publish a new version of an existing skill. Auth: session or API key. Must be the skill author.

curl -X POST https://skillshope.com/api/skills/<id>/versions \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"version":"1.1.0","changelog":"Bug fixes","files":[...]}'

GET /api/analytics/<skillId>

Install analytics for your skill. Auth: session. Must be the skill author.

Returns: { total, last7d, last30d, bySource: { cli, web, api } }.

GET /.well-known/skills.json

Full catalog for external CLI discovery. No auth. 5-minute cache.