{"openapi":"3.1.0","info":{"title":"ClawNet API","version":"1.0.0","description":"Discover, inspect, resolve, download, and publish on-chain agent skills. Requests are limited per client IP in fixed 60-second windows: 100 default and skill-read requests, 30 searches, 20 downloads, 10 skill writes, or 50 bot requests. Responses use the RFC RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and RateLimit-Policy headers; 429 responses also include Retry-After.","contact":{"name":"ClawNet project support","url":"https://clawnet.sh/contact"}},"externalDocs":{"description":"ClawNet Developer Documentation","url":"https://clawnet.sh/docs"},"servers":[{"url":"https://clawnet.sh"}],"paths":{"/api/v1/skills":{"get":{"operationId":"listSkills","summary":"List skills","description":"Lists public skills with cursor pagination and a selectable sort order.","parameters":[{"name":"limit","in":"query","description":"Maximum number of skills to return.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"sort","in":"query","description":"Result ordering.","schema":{"type":"string","enum":["updated","downloads","stars"],"default":"updated"}},{"name":"cursor","in":"query","description":"Opaque cursor returned by the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of skills.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillList"}}}},"default":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"publishSkill","summary":"Publish a skill","description":"Publishes a signed skill version. Authenticate with a Sigma Auth bearer token.","security":[{"sigmaAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishSkill"}}}},"responses":{"201":{"description":"The skill version was published.","content":{"application/json":{"schema":{"type":"object","required":["ok","slug","version"],"properties":{"ok":{"type":"boolean","const":true},"slug":{"type":"string"},"version":{"type":"string"}}}}}},"400":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills/{slug}":{"get":{"operationId":"getSkill","summary":"Get a skill","description":"Returns skill metadata, its latest version, and author information.","parameters":[{"name":"slug","in":"path","required":true,"description":"Registry slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"Skill details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillDetail"}}}},"404":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteSkill","summary":"Delete a skill","description":"Soft-deletes a skill owned by the authenticated BAP identity.","parameters":[{"name":"slug","in":"path","required":true,"description":"Registry slug.","schema":{"type":"string"}}],"security":[{"sigmaAuth":[]}],"responses":{"200":{"description":"The operation completed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"401":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills/{slug}/versions":{"get":{"operationId":"listSkillVersions","summary":"List skill versions","description":"Returns the ordered publication history for a skill slug.","parameters":[{"name":"slug","in":"path","required":true,"description":"Registry slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"Published versions.","content":{"application/json":{"schema":{"type":"object","required":["versions"],"properties":{"versions":{"type":"array","items":{"$ref":"#/components/schemas/VersionSummary"}}}}}}},"default":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills/{slug}/versions/{version}":{"get":{"operationId":"getSkillVersion","summary":"Get a skill version","description":"Returns the content, files, and chain metadata for one version.","parameters":[{"name":"slug","in":"path","required":true,"description":"Registry slug.","schema":{"type":"string"}},{"name":"version","in":"path","required":true,"description":"Semantic version.","schema":{"type":"string"}}],"responses":{"200":{"description":"A published skill version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillVersion"}}}},"404":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills/{slug}/file":{"get":{"operationId":"getSkillFile","summary":"Get a skill file","description":"Returns one raw file from the latest or requested skill version.","parameters":[{"name":"slug","in":"path","required":true,"description":"Registry slug.","schema":{"type":"string"}},{"name":"path","in":"query","required":true,"description":"Relative path inside the skill package.","schema":{"type":"string"}},{"name":"version","in":"query","description":"Version to read. Defaults to the latest version.","schema":{"type":"string"}}],"responses":{"200":{"description":"Raw file content.","content":{"text/plain":{"schema":{"type":"string"}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/search":{"get":{"operationId":"searchSkills","summary":"Search the registry","description":"Semantically searches skills, agents, organizations, or all registry entries.","parameters":[{"name":"q","in":"query","required":true,"description":"Natural-language search query.","schema":{"type":"string","minLength":1}},{"name":"type","in":"query","description":"Registry entry type to search.","schema":{"type":"string","enum":["skill","agent","organization","all"],"default":"skill"}},{"name":"limit","in":"query","description":"Maximum result count.","schema":{"type":"integer","minimum":1,"default":20}}],"responses":{"200":{"description":"Ranked registry results.","content":{"application/json":{"schema":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}}}}}}},"400":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/resolve":{"get":{"operationId":"resolveSkillVersion","summary":"Resolve a skill version","description":"Resolves a slug and optional version range to a published version.","parameters":[{"name":"slug","in":"query","required":true,"description":"Skill slug.","schema":{"type":"string"}},{"name":"version","in":"query","description":"Exact version or semantic version range.","schema":{"type":"string"}}],"responses":{"200":{"description":"Resolved version metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillVersion"}}}},"400":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/download":{"get":{"operationId":"downloadSkill","summary":"Download a skill","description":"Downloads a ZIP archive for the latest or requested skill version.","parameters":[{"name":"slug","in":"query","required":true,"description":"Skill slug.","schema":{"type":"string"}},{"name":"version","in":"query","description":"Version to download. Defaults to the latest version.","schema":{"type":"string"}}],"responses":{"200":{"description":"ZIP archive.","content":{"application/zip":{"schema":{"type":"string","contentEncoding":"binary"}}}},"400":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/downloads":{"post":{"operationId":"recordSkillDownload","summary":"Record an install","description":"Records anonymous install telemetry for a specific skill version.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug","version"],"properties":{"slug":{"type":"string"},"version":{"type":"string"}}}}}},"responses":{"204":{"description":"The install was recorded."},"400":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills/{slug}/undelete":{"post":{"operationId":"restoreSkill","summary":"Restore a skill","description":"Restores a soft-deleted skill owned by the authenticated BAP identity.","parameters":[{"name":"slug","in":"path","required":true,"description":"Registry slug.","schema":{"type":"string"}}],"security":[{"sigmaAuth":[]}],"responses":{"200":{"description":"The operation completed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"401":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stars/{slug}":{"post":{"operationId":"starSkill","summary":"Star a skill","description":"Adds a star from the authenticated BAP identity to a skill.","parameters":[{"name":"slug","in":"path","required":true,"description":"Registry slug.","schema":{"type":"string"}}],"security":[{"sigmaAuth":[]}],"responses":{"200":{"description":"Updated star state.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"unstarSkill","summary":"Unstar a skill","description":"Removes the authenticated BAP identity's star from a skill.","parameters":[{"name":"slug","in":"path","required":true,"description":"Registry slug.","schema":{"type":"string"}}],"security":[{"sigmaAuth":[]}],"responses":{"200":{"description":"Updated star state.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/whoami":{"get":{"operationId":"getCurrentIdentity","summary":"Get the current identity","description":"Validates a Sigma Auth token and returns its BAP identity and public key.","security":[{"sigmaAuth":[]}],"responses":{"200":{"description":"Authenticated public identity.","content":{"application/json":{"schema":{"type":"object","required":["user"],"properties":{"user":{"type":"object","required":["bapId","pubkey"],"properties":{"bapId":{"type":"string"},"pubkey":{"type":"string"}}}}}}}},"401":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"headers":{"RateLimitLimit":{"description":"Maximum requests permitted in the current 60-second window.","schema":{"type":"integer","minimum":1}},"RateLimitPolicy":{"description":"Applied quota and window in seconds.","schema":{"type":"string","example":"100;w=60"}},"RateLimitRemaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer","minimum":0}},"RateLimitReset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","minimum":0}},"RetryAfter":{"description":"Seconds to wait before retrying a rate-limited request.","schema":{"type":"integer","minimum":1}}},"securitySchemes":{"sigmaAuth":{"type":"http","scheme":"bearer","description":"Sigma Auth bearer token obtained through the ClawNet CLI login flow."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"hint":{"type":"string"}}},"Ok":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean","const":true}}},"File":{"type":"object","required":["path","content"],"properties":{"path":{"type":"string"},"content":{"type":"string"}}},"Skill":{"type":"object","required":["slug","name","description","authorBapId","latestVersion","starCount","createdAt","updatedAt"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"authorBapId":{"type":"string"},"latestVersion":{"type":"string"},"latestTxId":{"type":["string","null"]},"homepage":{"type":["string","null"],"format":"uri"},"tags":{"type":"array","items":{"type":"string"}},"starCount":{"type":"integer"},"downloadCount":{"type":"integer"},"downloadCountAllTime":{"type":"integer"},"deleted":{"type":"boolean"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}}},"SkillList":{"type":"object","required":["skills","hasMore"],"properties":{"skills":{"type":"array","items":{"$ref":"#/components/schemas/Skill"}},"hasMore":{"type":"boolean"},"cursor":{"type":["string","null"]}}},"VersionSummary":{"type":"object","required":["version","publishedAt","onChain"],"properties":{"version":{"type":"string"},"txId":{"type":["string","null"]},"prevTxId":{"type":["string","null"]},"changelog":{"type":["string","null"]},"publishedAt":{"type":"number"},"onChain":{"type":"boolean"}}},"SkillVersion":{"allOf":[{"$ref":"#/components/schemas/VersionSummary"},{"type":"object","properties":{"slug":{"type":"string"},"content":{"type":"string"},"contentType":{"type":"string"},"authorBapId":{"type":"string"},"files":{"type":"array","items":{"$ref":"#/components/schemas/File"}}}}]},"SkillDetail":{"type":"object","required":["skill","latestVersion"],"properties":{"skill":{"$ref":"#/components/schemas/Skill"},"latestVersion":{"anyOf":[{"$ref":"#/components/schemas/SkillVersion"},{"type":"null"}]},"author":{"type":["object","null"],"additionalProperties":true}}},"SearchResult":{"type":"object","required":["type","slug","name","description","score"],"properties":{"type":{"type":"string","enum":["skill","agent","organization"]},"slug":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"authorBapId":{"type":"string"},"latestVersion":{"type":"string"},"homepage":{"type":["string","null"],"format":"uri"},"score":{"type":"number"}}},"PublishSkill":{"type":"object","required":["slug","name","description","version","files"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"homepage":{"type":"string","format":"uri"},"tags":{"type":"array","items":{"type":"string"}},"changelog":{"type":"string"},"files":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/File"}},"aipSignature":{"type":"string"},"signerAddress":{"type":"string"},"opReturnHex":{"type":"string"}}}}}}