API Documentation

Access the Skills Directory programmatically.

Authentication

All API requests require an API key. Include it in your request headers:

# Using Authorization header
curl -H "Authorization: Bearer sk_live_your_key_here" \
  https://skillsdirectory.com/api/v1/skills

# Using x-api-key header
curl -H "x-api-key: sk_live_your_key_here" \
  https://skillsdirectory.com/api/v1/skills

Rate Limits

TierRequests/DayPrice

Free100$0

Pro1,000$29/mo

Enterprise10,000$199/mo

Rate limits reset daily at midnight UTC. Every response includes rate limit headers:

HeaderDescription

X-RateLimit-RemainingRequests left today

X-RateLimit-TierYour current tier

Endpoints

GET /api/v1/skills

List skills with filtering, sorting, and pagination.

ParameterTypeDescription

qstringSearch by name or description

categorystringFilter by category slug

sortstringrecent | votes | stars

limitintegerResults per page (max 100)

offsetintegerPagination offset

verifiedbooleanFilter verified skills only

securityGradestringMax grade (A-F, default: A, 'all' to disable)

minSecurityScoreintegerMinimum security score (0-100)

GET /api/v1/skills/:slug

Get a single skill by its slug.

GET /api/v1/skills/searchPro+

Semantic search using AI embeddings. Requires Pro or Enterprise tier.

ParameterTypeDescription

qstringSearch query (required)

limitintegerMax results (default 20, max 100)

categorystringFilter by category

thresholdfloatMin similarity (0-1, default 0.5)

Each result includes _score (combined relevance) and _similarity (vector similarity) fields.

GET /api/v1/categories

List all skill categories.

GET /api/v1/stats

Get your API key usage statistics, including a 7-day history.

{
  "data": {
    "key": {
      "prefix": "sk_live_abcd1234",
      "name": "My Key",
      "tier": "free",
      "status": "active",
      "createdAt": "2025-01-15T00:00:00.000Z"
    },
    "usage": {
      "today": 42,
      "remaining": 58,
      "limit": 100,
      "resetAt": "2025-02-12T00:00:00.000Z"
    },
    "history": [
      { "date": "2025-02-05", "requests": 87 },
      { "date": "2025-02-06", "requests": 64 }
    ]
  }
}

Response Format

All responses follow a consistent JSON structure:

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalCount": 44000,
    "totalPages": 2200,
    "hasNextPage": true,
    "hasPrevPage": false
  },
  "meta": {
    "requestsRemaining": 99,
    "tier": "free"
  }
}

Error Codes

StatusCodeDescription

400MISSING_PARAMETERRequired parameter missing

401MISSING_API_KEYNo API key provided

401INVALID_API_KEYInvalid or expired key

403TIER_RESTRICTEDEndpoint requires higher tier

404NOT_FOUNDResource not found

429RATE_LIMIT_EXCEEDEDDaily limit reached

Error responses use the format:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Skill \"my-skill\" not found."
  }
}

Data Access by Tier

Higher tiers get access to more skill fields:

FieldFreeProEnterprise

Basic info (name, description, tags)✓✓✓

Author & GitHub stars✓✓✓

Full content—✓✓

Security grade & score—✓✓

Semantic search—✓✓

GitHub metadata (forks, language)—✓✓

Security findings & analysis——✓

Content hashes——✓

Security Scanning

Every skill in the directory is automatically scanned for security issues using 50+ detection rules across 10 threat categories.

Grade Scale

GradeScore RangeMeaning

A90-100No significant issues found

B75-89Minor concerns, generally safe

C60-74Some issues, review recommended

D40-59Significant concerns

F0-39Critical security issues detected

Default Filtering

The skills listing defaults to securityGrade=A. Pass securityGrade=all to see all grades. For full details about our scanning methodology, see the Security page.

Ready to get started?