{"openapi":"3.0.3","info":{"title":"CleanSkills API","version":"3.0","description":"Verifiable skill certifications using the CLR standard. Agents submit skills for behavioral contract analysis, automated testing, and CLR-ID issuance. x402 payments to certified skill endpoints double as trust signals — successful payment implies the skill passed the 48-point behavioral test suite."},"servers":[{"url":"https://cleanskills.btnomb.com"}],"paths":{"/agent/certify":{"post":{"summary":"Request a skill certification","description":"Submit a skill for certification. Requires x402 payment, a credit code, or a master API key.","operationId":"submitCertification","security":[{"x402":[]},{"credit_code":[]},{"master_key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["skill","candidateName","candidateEmail"],"properties":{"skill":{"type":"string","description":"Name or identifier of the skill to certify"},"candidateName":{"type":"string","description":"Name of the candidate or agent"},"candidateEmail":{"type":"string","format":"email","description":"Contact email for status updates"},"evidence":{"type":"string","description":"Optional evidence or SKILL.md content"},"credit_code":{"type":"string","description":"Optional credit code for payment (alternative to x402)"},"webhook_url":{"type":"string","format":"uri","description":"Optional webhook URL for async status callbacks"}}}}}},"responses":{"200":{"description":"Certification request accepted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"clrId":{"type":"string"},"request_id":{"type":"string"},"status":{"type":"string"},"webhook_registered":{"type":"boolean"},"status_url":{"type":"string"},"estimatedDays":{"type":"integer"}}}}}}}}},"/api/verify/{clr_id}":{"get":{"summary":"Verify a certification by CLR-ID","description":"Check the verification status of a CLR certificate. Free, no authentication required.","operationId":"verifyCertification","parameters":[{"name":"clr_id","in":"path","required":true,"schema":{"type":"string"},"description":"The CLR-ID to verify"}],"responses":{"200":{"description":"Certification verification result","content":{"application/json":{"schema":{"type":"object","properties":{"clr_id":{"type":"string"},"status":{"type":"string","enum":["certified","pending","reviewing","failed","not_found"]},"skill":{"type":"string","nullable":true},"issued_at":{"type":"string","format":"date-time","nullable":true},"last_tested":{"type":"string","format":"date-time","nullable":true},"verified":{"type":"boolean"},"x402_trust":{"type":"boolean"},"issuer":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}}},"source":{"type":"string","nullable":true}}}}}}}}},"/api/registry":{"get":{"summary":"Machine-readable registry of certified skills","description":"Query the public registry of certified skills with filtering and pagination.","operationId":"listRegistry","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["certified","all","pending","rejected"]},"description":"Filter by status (default: certified)"},{"name":"capability","in":"query","schema":{"type":"string"},"description":"Filter by keyword in skill name"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Results per page"},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"Pagination offset"}],"responses":{"200":{"description":"Registry results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/RegistryEntry"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}}},"/api/certify/{request_id}/status":{"get":{"summary":"Poll certification request status","description":"Check the current status of a pending certification request.","operationId":"getCertificationStatus","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string"},"description":"The request ID or CLR-ID to check"}],"responses":{"200":{"description":"Certification status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertStatus"}}}}}}},"/api/credits/{code}":{"get":{"summary":"Check credit code balance","description":"Look up remaining credits and usage history for a credit code.","operationId":"checkCredits","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"},"description":"The credit code to check"}],"responses":{"200":{"description":"Credit code details","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"bundle":{"type":"string"},"credits_total":{"type":"integer"},"credits_remaining":{"type":"integer"},"jobs":{"type":"array","items":{"type":"string"}}}}}}}}}},"/api/credits/purchase":{"post":{"summary":"Purchase a credit bundle","description":"Buy skill credits via x402 payment. Returns a credit code for use with POST /agent/certify.","operationId":"purchaseCredits","security":[{"x402":[]},{"master_key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["bundle","email"],"properties":{"bundle":{"type":"string","enum":["solo","team","studio","enterprise","agent_bulk"]},"email":{"type":"string","format":"email"},"wallet":{"type":"string","description":"Optional wallet address"}}}}}},"responses":{"200":{"description":"Credits purchased successfully","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"code":{"type":"string"},"credits":{"type":"integer"},"bundle":{"type":"string"},"price":{"type":"number"}}}}}}}}},"/api/trial-cert":{"get":{"summary":"Claim a free trial certification credit","description":"Claim one free trial Skill Credit — one per email address. Use the returned credit_code with POST /agent/certify to certify your first skill at no cost.","operationId":"claimTrialCredit","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","format":"email"},"description":"Email address to associate with the trial credit"}],"responses":{"200":{"description":"Trial credit issued","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"credit_code":{"type":"string","description":"Use this code with POST /agent/certify"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid email or trial already claimed for this email"}}}},"/badge/{clr_id}.svg":{"get":{"summary":"SVG badge for a CLR certificate","description":"Returns a shields-style SVG badge for embedding in READMEs. Green \"certified\" for approved certs, amber \"pending\" for in-review. Cache-Control: no-cache so status updates live.","operationId":"getCertBadge","parameters":[{"name":"clr_id","in":"path","required":true,"schema":{"type":"string"},"description":"The CLR-ID to render a badge for"}],"responses":{"200":{"description":"SVG badge image","content":{"image/svg+xml":{"schema":{"type":"string"}}}}}}},"/cert/{clr_id}":{"get":{"summary":"Human-readable certificate detail page","description":"Returns a full HTML certificate page for the given CLR-ID, including skill name, tier, test results, issuer, and a README embed snippet. Suitable for sharing as a trust signal link.","operationId":"getCertPage","parameters":[{"name":"clr_id","in":"path","required":true,"schema":{"type":"string"},"description":"The CLR-ID to display"}],"responses":{"200":{"description":"HTML certificate page"},"404":{"description":"CLR-ID not found"}}}}},"components":{"schemas":{"CLRCertificate":{"type":"object","properties":{"clr_id":{"type":"string","description":"Unique CLR identifier"},"skill":{"type":"string"},"status":{"type":"string","enum":["certified","pending","reviewing","failed","not_found"]},"issued_at":{"type":"string","format":"date-time","nullable":true},"last_tested":{"type":"string","format":"date-time","nullable":true},"verified":{"type":"boolean"},"x402_trust":{"type":"boolean","description":"True if cert is verified AND issuer is BTNOMB CleanSkills. x402 payment to this cert doubles as a trust signal."},"issuer":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}}},"source":{"type":"string","nullable":true}}},"RegistryEntry":{"type":"object","properties":{"clr_id":{"type":"string"},"skill":{"type":"string","nullable":true},"status":{"type":"string"},"certified_at":{"type":"string","format":"date-time","nullable":true},"source":{"type":"string"},"issuer":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}}}}},"CertStatus":{"type":"object","properties":{"request_id":{"type":"string"},"clr_id":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","reviewing","passed","failed","not_found"]},"eta_hours":{"type":"integer","nullable":true},"submitted_at":{"type":"string","format":"date-time","nullable":true},"reviewed_at":{"type":"string","format":"date-time","nullable":true}}}},"securitySchemes":{"x402":{"type":"http","scheme":"bearer","description":"x402 micropayment protocol — send payment via Base (USDC or ETH) to the configured wallet address. Powered by Base. The x402 facilitator handles proof verification."},"credit_code":{"type":"apiKey","in":"header","name":"X-Credit-Code","description":"Credit code obtained from /api/credits/purchase or Stripe checkout. Can also be sent in the request body as credit_code."},"master_key":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Master API key for admin/testing access. Bypasses x402 payment verification."}}}}