{"openapi":"3.1.0","info":{"title":"The Playbook — Skill Exchange API","description":"Registry for portable agent skills: publish signed skill packages, search them, install them, rate them.","version":"1.0.0"},"paths":{"/api/v1/health":{"get":{"tags":["meta"],"summary":"Health","operationId":"health_api_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/feed.xml":{"get":{"tags":["feed"],"summary":"Rss Feed","operationId":"rss_feed_feed_xml_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/skills":{"get":{"tags":["skills"],"summary":"List Skills","operationId":"list_skills_api_v1_skills_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","description":"Search name/description/slug","default":"","title":"Q"},"description":"Search name/description/slug"},{"name":"category","in":"query","required":false,"schema":{"type":"string","default":"","title":"Category"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","description":"newest | top | downloads | name","default":"newest","title":"Sort"},"description":"newest | top | downloads | name"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["publish"],"summary":"Publish Skill","description":"Publish a new skill. Signature is verified server-side, then the skill\nenters the moderation queue (unless AUTO_APPROVE=true).","operationId":"publish_skill_api_v1_skills_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillPublish"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/skills/{slug}":{"get":{"tags":["skills"],"summary":"Get Skill","operationId":"get_skill_api_v1_skills__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/skills/{slug}/versions/{version}":{"get":{"tags":["skills"],"summary":"Get Version","description":"Download one version: full SKILL.md + signature + public key.\n\nVerify client-side with core.signing.verify_package() (or any ed25519\nimplementation) over canonical bytes: slug + \"\\n\" + version + \"\\n\" + skill_md.","operationId":"get_version_api_v1_skills__slug__versions__version__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"version","in":"path","required":true,"schema":{"type":"string","title":"Version"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/skills/{slug}/skill.md":{"get":{"tags":["skills"],"summary":"Read Skill Md","description":"Front-door reader: the latest approved SKILL.md as raw markdown.\n\nOpen this URL in a browser to read a skill solo — no JSON parsing.","operationId":"read_skill_md_api_v1_skills__slug__skill_md_get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/skills/{slug}/versions/{version}/skill.md":{"get":{"tags":["skills"],"summary":"Read Version Skill Md","description":"Raw SKILL.md of one specific version, as markdown.","operationId":"read_version_skill_md_api_v1_skills__slug__versions__version__skill_md_get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"version","in":"path","required":true,"schema":{"type":"string","title":"Version"}}],"responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/bundles":{"get":{"tags":["bundles"],"summary":"List Bundles","description":"List install bundles for every approved skill (latest version each).","operationId":"list_bundles_api_v1_bundles_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","description":"Search name/description/slug","default":"","title":"Q"},"description":"Search name/description/slug"},{"name":"category","in":"query","required":false,"schema":{"type":"string","default":"","title":"Category"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/bundles/{slug}":{"get":{"tags":["bundles"],"summary":"Download Bundle","description":"Download one skill as a zip bundle (SKILL.md + manifest + receipt).","operationId":"download_bundle_api_v1_bundles__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"version","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pin a version; default latest","title":"Version"},"description":"Pin a version; default latest"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/skills/{slug}/versions":{"post":{"tags":["publish"],"summary":"Publish Version","description":"Publish a new version of your own skill. Same verify + queue flow.","operationId":"publish_version_api_v1_skills__slug__versions_post","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionPublish"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/skills/{slug}/ratings":{"post":{"tags":["ratings"],"summary":"Rate Skill","description":"Rate a skill 1-5 stars. Re-rating updates your previous rating.","operationId":"rate_skill_api_v1_skills__slug__ratings_post","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RatingIn"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/installs":{"post":{"tags":["ratings"],"summary":"Record Install","description":"Log that a skill version was installed (feeds download counts).\n\nNo auth required -- anonymous installs count too. Call this after a\nsuccessful client-side signature verification.","operationId":"record_install_api_v1_installs_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstallIn"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/accounts":{"post":{"tags":["accounts"],"summary":"Create Account","description":"Register a publisher account. The response includes the API key in\nPLAINTEXT -- save it now, it is never shown again.\n\nPass ``referred_by`` with the handle of the publisher who referred you:\nwhen your first skill is approved, they earn a free Exchange Pro pass.","operationId":"create_account_api_v1_accounts_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/accounts/me":{"get":{"tags":["accounts"],"summary":"Me","operationId":"me_api_v1_accounts_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/accounts/me/pro-passes":{"get":{"tags":["accounts"],"summary":"My Pro Passes","description":"Pro passes this account has earned via referrals. Each ``token`` goes\nin the ``X-Pro-Pass`` header for free Exchange Pro (x402 seller) access.\nTreat tokens like credentials: whoever holds one rides free as you.","operationId":"my_pro_passes_api_v1_accounts_me_pro_passes_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ProPassOut"},"type":"array","title":"Response My Pro Passes Api V1 Accounts Me Pro Passes Get"}}}}}}},"/api/v1/accounts/referrals":{"get":{"tags":["accounts"],"summary":"Referrals Overview","description":"Operator view: every referral with referrer/referred handles and\nconversion state (moderators only).","operationId":"referrals_overview_api_v1_accounts_referrals_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ReferralOut"},"type":"array","title":"Response Referrals Overview Api V1 Accounts Referrals Get"}}}}}}},"/api/v1/accounts/me/keys":{"get":{"tags":["accounts"],"summary":"List Keys","operationId":"list_keys_api_v1_accounts_me_keys_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"tags":["accounts"],"summary":"Create Key","description":"Mint an extra API key. Plaintext shown once.","operationId":"create_key_api_v1_accounts_me_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/accounts/me/keys/{key_id}":{"delete":{"tags":["accounts"],"summary":"Revoke Key","operationId":"revoke_key_api_v1_accounts_me_keys__key_id__delete","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/moderation/queue":{"get":{"tags":["moderation"],"summary":"Queue","operationId":"queue_api_v1_moderation_queue_get","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","default":"pending","title":"Status"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/moderation/queue/{queue_id}/decide":{"post":{"tags":["moderation"],"summary":"Decide","description":"Approve or reject a queued submission. Approving a new skill makes it\npublic; approving a new version promotes it to latest.\n\nApproving a referred publisher's FIRST skill automatically converts their\nreferral and issues the referrer a pro pass (see ``referral`` in the\nresponse).","operationId":"decide_api_v1_moderation_queue__queue_id__decide_post","parameters":[{"name":"queue_id","in":"path","required":true,"schema":{"type":"string","title":"Queue Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModerateIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AccountCreate":{"properties":{"handle":{"type":"string","title":"Handle","examples":["curiouscirkits"]},"display_name":{"type":"string","title":"Display Name","examples":["Curious Cirkits"]},"referred_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Referred By","description":"Handle of the existing publisher who referred this account","examples":["zuckbot"]}},"type":"object","required":["handle","display_name"],"title":"AccountCreate"},"AccountOut":{"properties":{"id":{"type":"string","title":"Id"},"handle":{"type":"string","title":"Handle"},"display_name":{"type":"string","title":"Display Name"},"is_moderator":{"type":"boolean","title":"Is Moderator"},"created_at":{"title":"Created At"},"api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}},"type":"object","required":["id","handle","display_name","is_moderator","created_at"],"title":"AccountOut"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"InstallIn":{"properties":{"slug":{"type":"string","title":"Slug"},"version":{"type":"string","title":"Version","default":"latest"},"client":{"type":"string","title":"Client","default":"rest"}},"type":"object","required":["slug"],"title":"InstallIn"},"KeyCreate":{"properties":{"name":{"type":"string","title":"Name","default":"default","examples":["laptop"]}},"type":"object","title":"KeyCreate"},"KeyOut":{"properties":{"id":{"type":"string","title":"Id"},"key_prefix":{"type":"string","title":"Key Prefix"},"name":{"type":"string","title":"Name"},"created_at":{"title":"Created At"},"last_used_at":{"anyOf":[{},{"type":"null"}],"title":"Last Used At"},"revoked":{"type":"boolean","title":"Revoked"},"api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}},"type":"object","required":["id","key_prefix","name","created_at","revoked"],"title":"KeyOut"},"ModerateIn":{"properties":{"approve":{"type":"boolean","title":"Approve"},"note":{"type":"string","title":"Note","default":""}},"type":"object","required":["approve"],"title":"ModerateIn"},"ProPassOut":{"properties":{"pass_id":{"type":"string","title":"Pass Id"},"token":{"type":"string","title":"Token"},"issued_at":{"title":"Issued At"},"expires_at":{"title":"Expires At"}},"type":"object","required":["pass_id","token","issued_at","expires_at"],"title":"ProPassOut"},"RatingIn":{"properties":{"stars":{"type":"integer","maximum":5.0,"minimum":1.0,"title":"Stars"},"comment":{"type":"string","title":"Comment","default":""}},"type":"object","required":["stars"],"title":"RatingIn"},"ReferralOut":{"properties":{"id":{"type":"string","title":"Id"},"referrer_handle":{"type":"string","title":"Referrer Handle"},"referred_handle":{"type":"string","title":"Referred Handle"},"status":{"type":"string","title":"Status"},"created_at":{"title":"Created At"},"converted_at":{"anyOf":[{},{"type":"null"}],"title":"Converted At"},"pass_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pass Id"},"expires_at":{"anyOf":[{},{"type":"null"}],"title":"Expires At"}},"type":"object","required":["id","referrer_handle","referred_handle","status","created_at"],"title":"ReferralOut"},"SkillPublish":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"description":{"type":"string","title":"Description"},"category":{"type":"string","title":"Category","default":"general"},"version":{"type":"string","title":"Version","default":"1.0.0"},"skill_md":{"type":"string","title":"Skill Md","description":"Full SKILL.md content"},"manifest":{"additionalProperties":true,"type":"object","title":"Manifest"},"signature":{"type":"string","title":"Signature","description":"Base64 ed25519 signature"},"public_key":{"type":"string","title":"Public Key","description":"Hex ed25519 public key"}},"type":"object","required":["name","slug","description","skill_md","signature","public_key"],"title":"SkillPublish"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VersionPublish":{"properties":{"version":{"type":"string","title":"Version"},"skill_md":{"type":"string","title":"Skill Md"},"manifest":{"additionalProperties":true,"type":"object","title":"Manifest"},"signature":{"type":"string","title":"Signature"},"public_key":{"type":"string","title":"Public Key"}},"type":"object","required":["version","skill_md","signature","public_key"],"title":"VersionPublish"}}}}