{"openapi":"3.0.3","info":{"title":"FindSkills Agent API","version":"1.0.0","description":"AI Agent-friendly API for the FindSkills directory. Provides structured, token-optimized access to 89,000+ AI Agent Skills. Rate limits — per-IP: 30 req/min (all tiers). Per-identity: Guest 15 unique detail lookups/5min + 30 unique searches/10min; Registered (signed in with API key) 100 unique detail lookups/5min + 100 searches/10min. Daily result quota: Guest 30/day, Registered 300/day. Responses are CDN-cached for 5 minutes. Authentication: Guest (no key) receives limited fields (name, description, tags, category, safety_label). Pass an API key via Authorization: Bearer header. API keys are free during preview — sign in with GitHub at https://findskills.org/developers to mint a key and unlock full fields (id, url, author, stars, source). Tip: call GET /stats first for a quick dataset overview.","contact":{"url":"https://findskills.org"},"license":{"name":"MIT"}},"servers":[{"url":"https://findskills.org/api/v1"}],"paths":{"/stats":{"get":{"operationId":"getStats","summary":"Get dataset overview","description":"Returns total skill count, last updated date, and breakdowns by category, source, and auth type. Call this first to understand the dataset.","responses":{"200":{"description":"Dataset statistics","content":{"application/json":{"schema":{"type":"object","properties":{"total_skills":{"type":"integer","example":14045},"last_updated":{"type":"string","format":"date","example":"2026-02-27","nullable":true},"categories":{"type":"object","additionalProperties":{"type":"integer"},"example":{"search":1203,"coding":2841}},"sources":{"type":"object","additionalProperties":{"type":"integer"},"example":{"clawhub":245,"github":13762}},"auth_types":{"type":"object","additionalProperties":{"type":"integer"},"example":{"none":12000,"api_key":1500}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/skills":{"get":{"operationId":"listSkills","summary":"List skills with filtering and pagination","description":"Returns a token-optimized list of skills. Guest callers receive GuestSkillCompact (name, description, tags, category, safety_label). 12 daily featured skills are returned with full SkillCompact fields plus _featured: true, and are sorted to the front of the first page for guest callers. Authenticated callers (API key or session) receive SkillCompact with full fields. Use the `fields` parameter (authenticated only) to request additional fields. Response includes `next`/`prev` pagination URLs when applicable.","parameters":[{"name":"q","in":"query","schema":{"type":"string","minLength":2,"maxLength":200},"description":"Filter by keyword in name, description, tags, or author (2-200 chars)"},{"name":"tags","in":"query","schema":{"type":"string"},"description":"Comma-separated tag filter (OR match)"},{"name":"source","in":"query","schema":{"type":"string","enum":["clawhub","github","smithery","manual"]},"description":"Filter by data source"},{"name":"auth_type","in":"query","schema":{"type":"string","enum":["none","api_key","oauth2","bearer"]},"description":"Filter by authentication requirement"},{"name":"category","in":"query","schema":{"type":"string","enum":["search","coding","data","communication","media","automation","security","ai-ml","devops","finance","productivity","integration","other"]},"description":"Filter by category"},{"name":"sort","in":"query","schema":{"type":"string","enum":["updated","added","stars","quality","safety","name"],"default":"updated"},"description":"Sort order"},{"name":"min_quality","in":"query","schema":{"type":"integer","minimum":0,"maximum":100},"description":"Minimum quality score (0-100). Only return skills scoring at or above this threshold."},{"name":"min_safety","in":"query","schema":{"type":"integer","minimum":0,"maximum":100},"description":"Minimum safety score (0-100). Only return skills scoring at or above this threshold."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Results per page (max 100)"},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"Pagination offset"},{"name":"fields","in":"query","schema":{"type":"string"},"description":"Comma-separated list of fields to include. Available: id, name, description, author, url, tags, auth_type, source, category, stars, downloads, created_at, updated_at, auth_requirements, safety_label"}],"responses":{"200":{"description":"Paginated skill list","content":{"application/json":{"schema":{"type":"object","properties":{"skills":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/SkillCompact"},{"$ref":"#/components/schemas/GuestSkillCompact"}]}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"next":{"type":"string","nullable":true,"description":"URL for next page (null if last page)"},"prev":{"type":"string","nullable":true,"description":"URL for previous page (null if first page)"}}}}}},"400":{"description":"Invalid parameters (query too short, offset too deep)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/skills/{id}":{"get":{"operationId":"getSkill","summary":"Get full skill details by ID","description":"Returns skill details by ID. Guest callers receive GuestSkillFull (quality tier and safety tier without identifiable fields). Authenticated callers (API key or session) receive the complete SkillFull record including auth_requirements and openapi_spec.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Skill ID (e.g. \"clawhub-web-search\")"}],"responses":{"200":{"description":"Full skill detail","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SkillFull"},{"$ref":"#/components/schemas/GuestSkillFull"}]}}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/search":{"get":{"operationId":"searchSkills","summary":"Weighted relevance search","description":"Searches skills with weighted scoring: name(10) > tags(4) > author(3) > description(1). Default sort is by relevance. Use sort parameter to re-order results (e.g. sort=quality, sort=stars). Guest callers receive GuestSkillCompact; authenticated callers receive SkillCompact.","parameters":[{"name":"q","in":"query","schema":{"type":"string","minLength":2,"maxLength":200},"description":"Primary search query parameter (2-200 chars)"},{"name":"query","in":"query","schema":{"type":"string","minLength":2,"maxLength":200},"description":"Alias of q. Use either q or query (2-200 chars)."},{"name":"sort","in":"query","schema":{"type":"string","enum":["relevance","quality","safety","stars","name","added","updated"],"default":"relevance"},"description":"Sort order (default: relevance)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Search results (sorted by relevance or specified sort parameter)","content":{"application/json":{"schema":{"type":"object","properties":{"skills":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/SkillCompact"},{"$ref":"#/components/schemas/GuestSkillCompact"}]}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"query":{"type":"string"},"sort":{"type":"string","description":"Applied sort order"},"next":{"type":"string","nullable":true,"description":"URL for next page"},"prev":{"type":"string","nullable":true,"description":"URL for previous page"}}}}}},"400":{"description":"Missing q/query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/tags":{"get":{"operationId":"listTags","summary":"List all tags with usage counts","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":50},"description":"Max tags to return"}],"responses":{"200":{"description":"Tag list sorted by count (descending)","content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"count":{"type":"integer"}}}},"total":{"type":"integer"}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"schemas":{"GuestSkillCompact":{"type":"object","description":"Limited skill representation returned to unauthenticated (Guest) callers. Does not include id, url, author, stars, or source. Exception: 12 daily featured skills return full SkillCompact fields plus _featured: true.","properties":{"name":{"type":"string","example":"Web Search"},"description":{"type":"string","example":"Enable AI Agent to perform real-time web search"},"tags":{"type":"array","items":{"type":"string"},"example":["search","web"]},"category":{"type":"string","example":"search"},"safety_label":{"type":"string","enum":["verified","community","caution","untested"],"example":"verified"},"_hint":{"type":"string","description":"Upgrade hint with link to get a free API key (non-featured skills only)"},"_featured":{"type":"boolean","description":"Present and true only on the 12 daily featured skills. Featured skills include full SkillCompact fields (id, url, author, stars, source)."}}},"GuestSkillFull":{"type":"object","description":"Limited detail record returned to unauthenticated (Guest) callers. Includes quality/safety tiers but no identifiable fields (id, url, author, stars, source).","properties":{"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"category":{"type":"string","nullable":true},"updated_at":{"type":"string","format":"date","nullable":true},"quality":{"type":"object","properties":{"quality_tier":{"type":"string","enum":["high","medium","low"]},"has_skill_md":{"type":"boolean"},"freshness_days":{"type":"integer","nullable":true}}},"safety":{"type":"object","properties":{"safety_tier":{"type":"string","enum":["verified","community","caution"]},"safety_label":{"type":"string","enum":["verified","community","caution","untested"]}}},"_hint":{"type":"string","description":"Upgrade hint with link to get a free API key"},"indexable":{"type":"boolean","description":"Whether this skill is included in the public sitemap and served with index meta robots. Mirrors the SSR indexability signal (lib/seo.js::isIndexable)."}}},"SkillCompact":{"type":"object","description":"Token-optimized skill representation for listings — returned to authenticated callers (API key or session)","properties":{"id":{"type":"string","example":"clawhub-web-search"},"name":{"type":"string","example":"Web Search"},"description":{"type":"string","example":"Enable AI Agent to perform real-time web search"},"author":{"type":"string","example":"openclaw"},"tags":{"type":"array","items":{"type":"string"},"example":["search","web"]},"category":{"type":"string","enum":["search","coding","data","communication","media","automation","security","ai-ml","devops","finance","productivity","integration","other"],"example":"search"},"source":{"type":"string","enum":["clawhub","github","smithery","manual"],"example":"clawhub"},"url":{"type":"string","format":"uri","example":"https://github.com/openclaw/openclaw"},"stars":{"type":"integer","description":"GitHub star count","example":128},"safety_label":{"type":"string","enum":["verified","community","caution","untested"],"description":"Fuzzy safety label (no numeric score exposed)","example":"verified"},"_featured":{"type":"boolean","description":"Present and true on the 12 daily featured skills when returned to guest callers"}}},"SkillFull":{"type":"object","description":"Complete skill record — returned to authenticated callers (API key or session). Includes auth details, quality signals, and optional OpenAPI spec","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"url":{"type":"string","format":"uri"},"source":{"type":"string","enum":["clawhub","github","smithery","manual"]},"tags":{"type":"array","items":{"type":"string"}},"category":{"type":"string","enum":["search","coding","data","communication","media","automation","security","ai-ml","devops","finance","productivity","integration","other"]},"stars":{"type":"integer"},"updated_at":{"type":"string","format":"date","nullable":true},"auth_requirements":{"$ref":"#/components/schemas/AuthRequirements"},"quality":{"$ref":"#/components/schemas/QualitySignals"},"safety":{"$ref":"#/components/schemas/SafetySignals"},"openapi_spec":{"description":"OpenAPI 3.0+ spec for this skill (if available)","nullable":true,"type":"object"},"indexable":{"type":"boolean","description":"Whether this skill is included in the public sitemap and served with index meta robots. Mirrors the SSR indexability signal (lib/seo.js::isIndexable)."}}},"QualitySignals":{"type":"object","description":"Multi-dimensional quality signals for assessing skill trustworthiness","properties":{"quality_score":{"type":"integer","minimum":0,"maximum":100,"description":"Composite score (0-100)"},"license":{"type":"string","nullable":true,"description":"SPDX license identifier (e.g. MIT, Apache-2.0)","example":"MIT"},"archived":{"type":"boolean","description":"Whether the source repo is archived (unmaintained)"},"has_skill_md":{"type":"boolean","description":"Whether the repo contains a SKILL.md file with frontmatter"},"has_description":{"type":"boolean","description":"Whether the skill has a real description (not a placeholder)"},"forks":{"type":"integer","description":"Number of forks (community adoption signal)"},"language":{"type":"string","nullable":true,"description":"Primary programming language"},"freshness_days":{"type":"integer","nullable":true,"description":"Days since last update"}}},"SafetySignals":{"type":"object","description":"Safety assessment signals for evaluating skill trustworthiness before granting agent execution","properties":{"safety_score":{"type":"integer","minimum":0,"maximum":100,"description":"Composite safety score (0-100)"},"safety_tier":{"type":"string","enum":["verified","community","caution"],"description":"Safety tier: verified (>=70), community (>=40), caution (<40)"},"has_license":{"type":"boolean"},"not_archived":{"type":"boolean"},"repo_age_days":{"type":"integer","nullable":true},"recent_activity":{"type":"boolean","description":"Whether the repo was updated within the last 365 days"},"has_skill_md":{"type":"boolean"},"has_description":{"type":"boolean"},"community_trust":{"type":"integer","description":"Star count as community trust signal"},"known_org":{"type":"boolean"},"repo_size_kb":{"type":"integer"},"suspicious_patterns":{"type":"array","items":{"type":"string"},"description":"Detected suspicious patterns in SKILL.md (e.g. eval, base64)"}}},"AuthRequirements":{"type":"object","description":"Machine-readable authentication requirements for invoking a skill","required":["type"],"properties":{"type":{"type":"string","enum":["none","api_key","oauth2","bearer"],"description":"Authentication method required"},"placement":{"type":"string","enum":["header","query","body"],"description":"Where to send the credential"},"header_name":{"type":"string","description":"Header name if placement is header (e.g. \"Authorization\", \"X-API-Key\")"},"query_param":{"type":"string","description":"Query parameter name if placement is query"},"setup_url":{"type":"string","format":"uri","description":"URL where users can obtain credentials"}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}}},"responses":{"RateLimited":{"description":"Rate limit exceeded. Limits: per-IP 30 req/min; per-identity detail lookups Guest 15/5min, Registered 100/5min, Pro 200/5min; unique searches Guest 30/10min, Registered 100/10min, Pro 200/10min; daily results Guest 10/day, Registered 30/day, Pro 2,500/day.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until rate limit resets"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"retry_after_seconds":{"type":"integer"}}}}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Preferred method. Pass your API key as: Authorization: Bearer fs-key-xxx. API keys are free during preview — sign in with GitHub at https://findskills.org/developers. Unlocks full skill fields (id, url, author, stars, source)."},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Alternative method. Pass your API key as: x-api-key: fs-key-xxx. Same free-preview key from https://findskills.org/developers."}}},"security":[{},{"BearerAuth":[]},{"ApiKeyAuth":[]}]}