API Reference

Build integrations with Skillsmith using our HTTP API. Search skills, fetch skill details, and request recommendations programmatically over plain HTTP — no SDK required.

Base URL

All endpoints are served from the Skillsmith API gateway:

https://api.skillsmith.app

The gateway proxies to the underlying Supabase Edge Functions. The direct Supabase origin path is https://<project-ref>.supabase.co/functions/v1 — paths are identical, only the host differs. Prefer the proxy base (api.skillsmith.app) for production traffic; it terminates TLS, applies rate limiting, and shields the origin. Endpoint paths are RPC-style function names (/skills-search, not /skills), so this is an HTTP API, not a REST resource API.

Authentication

Pass your API key in the X-API-Key request header. Keys are tier-scoped and unlock higher rate limits. Keys are available at account settings.

X-API-Key: $SKILLSMITH_API_KEY

Search and skill-detail endpoints are also reachable unauthenticated at a low anonymous rate limit, but authenticated requests are strongly recommended for any integration.

Quick Start

Search for skills with a single GET request:

curl "https://api.skillsmith.app/skills-search?query=testing&trust_tier=verified&limit=10" \
  -H "X-API-Key: $SKILLSMITH_API_KEY"

Endpoints

GET /skills-search

Full-text search across skills with optional filters, passed as URL query-string parameters. Results are ranked by relevance and quality score.

Parameters

Example

curl "https://api.skillsmith.app/skills-search?query=git&category=Testing&trust_tier=verified&min_score=80&limit=5" \
  -H "X-API-Key: $SKILLSMITH_API_KEY"

Response (SearchResponse):

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "jest-helper",
      "description": "Helper utilities for Jest testing",
      "author": "community",
      "repo_url": "https://github.com/example/jest-helper",
      "quality_score": 0.85,
      "trust_tier": "verified",
      "tags": ["testing", "jest", "javascript"],
      "stars": 150,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-15T00:00:00Z",
      "categories": ["Testing", "Development"],
      "rank": 0.92
    }
  ],
  "meta": {
    "query": "git",
    "total": 1,
    "limit": 5,
    "offset": 0,
    "filters": { "category": "Testing", "trust_tier": "verified", "min_score": 80 }
  }
}

GET /skills-get

Retrieve detailed information about a single skill. The id query parameter accepts a UUID, an author/name identifier (e.g. anthropic/commit), or a fuzzy skill name.

Example

curl "https://api.skillsmith.app/skills-get?id=anthropic/commit" \
  -H "X-API-Key: $SKILLSMITH_API_KEY"

Response (SkillResponse) wraps a single skill in data:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "commit",
    "description": "Generate conventional commit messages",
    "author": "anthropic",
    "repo_url": "https://github.com/anthropic/commit",
    "quality_score": 0.93,
    "trust_tier": "official",
    "tags": ["git", "commit"],
    "stars": 1200,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-20T00:00:00Z",
    "categories": ["DevOps"]
  }
}

POST /skills-recommend

Get skill recommendations ranked by relevance to your technology stack.

Parameters

Example

curl -X POST https://api.skillsmith.app/skills-recommend \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $SKILLSMITH_API_KEY" \
  -d '{
    "stack": ["typescript", "react", "jest"],
    "project_type": "web",
    "limit": 10
  }'

Response (RecommendResponse) mirrors the search shape — a data array of skills (each with an optional relevance_score) plus a meta object echoing stack, project_type, total, and limit.

POST /events

Record an anonymous telemetry event. No personally identifiable information is collected; anonymous_id must be a client-generated hex hash, never a user identifier.

curl -X POST https://api.skillsmith.app/events \
  -H "Content-Type: application/json" \
  -d '{
    "event": "search",
    "anonymous_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "metadata": { "query": "testing", "results_count": 12 }
  }'

Returns { "ok": true } on success.

Wire Schema (JSON Response Shape)

All endpoints return snake_case JSON. The Skill object below is the canonical wire schema returned inside data by every skill-returning endpoint. Timestamps are ISO 8601 strings.

// Skill — wire schema (JSON response shape), snake_case
{
  id: string;                    // UUID
  name: string;                  // Skill name
  description: string | null;    // Skill description
  author: string | null;         // Author identifier
  repo_url: string | null;       // Source repository URL
  quality_score: number | null;  // 0-1 float (see Quality Score)
  trust_tier: TrustTier;         // Trust level
  tags: string[];                // Searchable tags
  stars: number | null;          // GitHub stars count
  created_at: string;            // ISO 8601 timestamp
  updated_at: string;            // ISO 8601 timestamp
  categories?: string[];         // Associated category names
}

Search results additionally carry a rank (relevance), and recommendation results carry a relevance_score.

Category

Category values are case-sensitive Titlecase strings. Pass them exactly as written — ?category=Testing matches, ?category=testing does not.

type Category =
  | 'Development'
  | 'Testing'
  | 'DevOps'
  | 'Documentation'
  | 'Productivity'
  | 'Security';

TrustTier

Five trust tiers, from highest assurance to lowest. See the trust tiers guide for criteria and promotion rules.

type TrustTier = 'official' | 'verified' | 'curated' | 'community' | 'unverified';

Quality Score

Quality is expressed on two different scales, so be careful not to mis-filter: the min_score query parameter takes a 0–100 integer, while the quality_score field in responses is a 0–1 float — a response value of 0.85 corresponds to a min_score of 85.

Rate Limiting

API requests are rate-limited based on your plan:

Each response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix timestamp) headers, plus an X-Request-ID for support correlation.

Error Responses

Errors return a non-2xx status and a JSON body with an error message and optional details:

{
  "error": "Query must be at least 3 characters",
  "details": { "parameter": "query", "received": "ab" }
}

Enterprise Audit & SIEM

Audit-log access and SIEM export are exposed as MCP tools, not HTTP endpoints. They run through the Skillsmith MCP server on the Enterprise tier — there is no api.skillsmith.app path for them.

SIEM Wire Formats

siem_export emits audit events in one of three wire formats, selectable per export:

webhook_configure

MCP tool — in preview, availability pending a production migration. Configure HMAC-SHA256 signed webhooks for skill events (install, uninstall, update, audit) to integrate with external SIEM, incident-response, or notification pipelines.

api_key_manage

MCP tool — in preview, availability pending a production migration. Manage API keys for programmatic access — list, create, rotate, and revoke keys scoped to your workspace.

OpenAPI Specification

A machine-readable OpenAPI 3.0 specification is available at www.skillsmith.app/openapi.yaml. Import it into Postman, Insomnia, or any OpenAPI-compatible client to explore all endpoints.

Lifecycle Tutorials

The HTTP API endpoints above back the search, get_skill, and recommend MCP tools that the CLI and MCP server expose. The lifecycle tutorials are MCP-tool and CLI walkthroughs — they do not call these HTTP endpoints directly, but rely on the same underlying data:

• Discover — uses the search and recommend MCP tools (backed by /skills-search and /skills-recommend).
• Evaluate — uses the get_skill, compare, and skill_diff MCP tools (skill detail backed by /skills-get).
• Govern — uses the Enterprise audit_query, audit_export, and siem_export MCP tools (see Enterprise Audit & SIEM for the wire format details).