{"openapi":"3.1.0","info":{"title":"AffiliateRoll API","version":"1.0.0","description":"Free API to search and compare affiliate programs. No authentication required.","contact":{"email":"hello@affiliateroll.com","url":"https://www.affiliateroll.com"}},"servers":[{"url":"https://www.affiliateroll.com","description":"Production"}],"paths":{"/api/v1/programs":{"get":{"operationId":"listPrograms","summary":"Search and list affiliate programs","description":"Returns a paginated list of affiliate programs. Supports filtering by category, commission type, search query, and sorting.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search query to filter programs by name or description"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by category slug (e.g., 'saas-software', 'e-commerce')"},{"name":"commission_type","in":"query","schema":{"type":"string"},"description":"Filter by commission type (e.g., 'percentage', 'flat_rate', 'recurring')"},{"name":"sort","in":"query","schema":{"type":"string","enum":["score","name","newest","commission"],"default":"score"},"description":"Sort order"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Number of results per page"},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"Pagination offset"}],"responses":{"200":{"description":"List of programs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Program"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}}},"/api/v1/programs/{slug}":{"get":{"operationId":"getProgram","summary":"Get program details by slug","description":"Returns full details for a single affiliate program including score breakdown, pros, cons, features, and reviews.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Program URL slug (e.g., 'amazon-associates')"}],"responses":{"200":{"description":"Program details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProgramDetail"}}}}}},"404":{"description":"Program not found"}}}},"/api/v1/categories":{"get":{"operationId":"listCategories","summary":"List all program categories","description":"Returns all categories with their program counts.","responses":{"200":{"description":"List of categories","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}}}}}}}},"/api/v1/categories/{slug}":{"get":{"operationId":"getCategory","summary":"Get category details with programs","description":"Returns a category and all its affiliate programs.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Category URL slug"}],"responses":{"200":{"description":"Category with programs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CategoryDetail"}}}}}},"404":{"description":"Category not found"}}}}},"components":{"schemas":{"Commission":{"type":"object","properties":{"type":{"type":"string","description":"Commission type (e.g., 'percentage', 'flat_rate', 'recurring', 'tiered', 'hybrid')"},"rate":{"type":"string","nullable":true,"description":"Human-readable commission rate string"},"min":{"type":"number","nullable":true},"max":{"type":"number","nullable":true}}},"Score":{"type":"object","nullable":true,"description":"AffiliateRoll Score. Standard and Featured listings, plus programs listed before 2026-09-29, are scored; null for newer Basic listings.","properties":{"value":{"type":"integer","minimum":0,"maximum":100},"label":{"type":"string","description":"Human-readable score label (e.g., 'Excellent', 'Good')"}}},"Program":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"url":{"type":"string","format":"uri"},"affiliate_url":{"type":"string","format":"uri","nullable":true},"logo_url":{"type":"string","format":"uri","nullable":true},"commission":{"$ref":"#/components/schemas/Commission"},"cookie_duration_days":{"type":"integer","nullable":true},"minimum_payout":{"type":"number","nullable":true},"payment_methods":{"type":"array","items":{"type":"string"}},"pros":{"type":"array","items":{"type":"string"}},"cons":{"type":"array","items":{"type":"string"}},"category":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"score":{"$ref":"#/components/schemas/Score"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ScoreBreakdown":{"type":"object","properties":{"commission":{"type":"integer"},"cookie_duration":{"type":"integer"},"minimum_payout":{"type":"integer"},"payment_methods":{"type":"integer"},"completeness":{"type":"integer"}}},"Review":{"type":"object","properties":{"authorName":{"type":"string","nullable":true},"authorTitle":{"type":"string","nullable":true},"content":{"type":"string"},"rating":{"type":"integer","nullable":true},"source":{"type":"string","nullable":true}}},"ProgramDetail":{"allOf":[{"$ref":"#/components/schemas/Program"},{"type":"object","properties":{"short_description":{"type":"string","nullable":true},"features":{"type":"array","items":{"type":"string"}},"score":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/Score"},{"type":"object","properties":{"breakdown":{"$ref":"#/components/schemas/ScoreBreakdown"}}}]},"reviews":{"type":"array","items":{"$ref":"#/components/schemas/Review"}}}}]},"Category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"program_count":{"type":"integer"}}},"CategoryProgram":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"commission_rate":{"type":"string","nullable":true},"commission_type":{"type":"string"},"cookie_duration_days":{"type":"integer","nullable":true},"score":{"$ref":"#/components/schemas/Score"}}},"CategoryDetail":{"allOf":[{"$ref":"#/components/schemas/Category"},{"type":"object","properties":{"programs":{"type":"array","items":{"$ref":"#/components/schemas/CategoryProgram"}}}}]},"PaginationMeta":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}