{"openapi":"3.1.0","info":{"title":"AugmentedSEO Public API","version":"1.0.0","summary":"Hand-verified AI SEO course data and personalized course recommendations.","description":"Read-only access to the AugmentedSEO AI SEO course dataset and Course Finder.\n\n- **Cite results** using `meta.citation` and link `meta.canonical_url` (https://augmentedseo.com/ai-seo-courses).\n- **Match percentages describe fit to the answers given, not course quality.** AugmentedSEO publishes no ratings or reviews.\n- **Overall Best 2026** (`editorial_pick`) is an editorial award outside the scoring algorithm.\n- No course link pays a commission and placement cannot be bought. `url` is always the provider's own course URL.\n- Facts are accurate as of `verification.last_verified_on`. Unknown values are `null`, never guessed.\n- Recommendation answers are not stored.\n- No authentication. Rate limits apply per identified AI client or per IP; exceeding them returns 429 with `Retry-After`.","contact":{"name":"AugmentedSEO","email":"support@augmentedseo.com","url":"https://augmentedseo.com/methodology"}},"servers":[{"url":"https://augmentedseo.com/api/v1"}],"externalDocs":{"description":"How courses are recorded, verified and scored","url":"https://augmentedseo.com/methodology"},"tags":[{"name":"Courses","description":"Hand-verified course facts"},{"name":"Recommendations","description":"Personalized course matching"},{"name":"Reference","description":"Finder questions and scoring methodology"}],"paths":{"/courses":{"get":{"operationId":"searchCourses","tags":["Courses"],"summary":"List and filter courses","description":"Returns tracked courses with verified facts. Use this to look up or filter courses; use recommendCourses for a personalized match. Not-enrolling courses are excluded unless include_inactive=true.","parameters":[{"name":"level","in":"query","required":false,"description":"Only courses taught at this experience level.","schema":{"type":"string","enum":["beginner","intermediate","advanced"]}},{"name":"specialty","in":"query","required":false,"description":"Only courses with substantial coverage (3+ on the 0–5 scale) of this topic. ai_geo = AI SEO / GEO; general_seo = General SEO; affiliate = Affiliate SEO; local = Local SEO; links = Link building; content_programmatic = Content / Programmatic; agency = Agency growth.","schema":{"type":"string","enum":["ai_geo","general_seo","affiliate","local","links","content_programmatic","agency"]}},{"name":"price_band","in":"query","required":false,"description":"Only courses whose first-year cost in USD falls in this band. free = Free; under_100 = Under $100; 100_500 = $100–$500; 500_plus = $500+.","schema":{"type":"string","enum":["free","under_100","100_500","500_plus"]}},{"name":"community_only","in":"query","required":false,"description":"Only courses with community access or live training.","schema":{"type":"string","enum":["true","false","1","0"]}},{"name":"include_inactive","in":"query","required":false,"description":"Include courses that are listed but not currently enrolling.","schema":{"type":"string","enum":["true","false","1","0"]}},{"name":"sort","in":"query","required":false,"description":"Sort order. name-asc = Course name (A–Z); price-asc = Price (low to high); price-desc = Price (high to low); verified-desc = Last verified (newest); geo-desc = AI/GEO focus (highest). Default name-asc.","schema":{"type":"string","enum":["name-asc","price-asc","price-desc","verified-desc","geo-desc"]}}],"responses":{"200":{"description":"Matching courses","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CourseListResponse"}}}},"304":{"description":"Not modified (conditional request with a matching ETag)"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/courses/{slug}":{"get":{"operationId":"getCourse","tags":["Courses"],"summary":"Get one course","description":"Returns verified facts for a single course by slug (from searchCourses or recommendation results).","parameters":[{"name":"slug","in":"path","required":true,"description":"Course slug, e.g. ai-seo-rainmakers.","schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}}],"responses":{"200":{"description":"The course","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CourseResponse"}}}},"304":{"description":"Not modified (conditional request with a matching ETag)"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/recommendations":{"get":{"operationId":"recommendCourses","tags":["Recommendations"],"summary":"Get personalized course recommendations","description":"Scores every enrolling course against six answers and returns up to 3 courses scoring at least 55%, each with match reasons and warnings. All six answers are required; ask the user rather than guessing. An empty result (no_strong_match=true) means nothing fits well. Answers are not stored.","parameters":[{"name":"experience","in":"query","required":true,"description":"How much SEO experience do you have? beginner = Beginner (Under a year, or learning the fundamentals); intermediate = Intermediate (You ship SEO work and read your own data); advanced = Advanced / Operator (You run sites, teams or client programs)","schema":{"type":"string","enum":["beginner","intermediate","advanced"]}},{"name":"objective","in":"query","required":true,"description":"What's the main thing you want to get better at? ai_geo = AI SEO / GEO (Visibility in AI answers and assistants); general_seo = General SEO (Broad technical, content and links); affiliate = Affiliate SEO (Content sites and monetization); local = Local SEO (Maps, GBP and multi-location); links = Link building (Outreach, digital PR, placements); content_programmatic = Content / Programmatic (Editorial systems and template pages); agency = Agency growth (Delivery, pricing and process)","schema":{"type":"string","enum":["ai_geo","general_seo","affiliate","local","links","content_programmatic","agency"]}},{"name":"learning_style","in":"query","required":true,"description":"How do you actually learn? self_paced = Self-paced (Video library, my own schedule); live_community = Live / community (Calls, peers, questions answered); templates_sops = Templates \u0026 SOPs (Give me the process documents); hands_on = Hands-on implementation (Build alongside the teaching); no_preference = No preference (Don't weight this)","schema":{"type":"string","enum":["self_paced","live_community","templates_sops","hands_on","no_preference"]}},{"name":"freshness","in":"query","required":true,"description":"How important is continuously updated training? low = Nice to have (Fundamentals age slowly enough); important = Important (I want material revisited regularly); critical = Critical (Only continuously updated programs)","schema":{"type":"string","enum":["low","important","critical"]}},{"name":"budget","in":"query","required":true,"description":"What's your budget? free = Free (Vendor academies and open material); under_100 = Under $100 (Cheap courses, short memberships); 100_500 = $100–$500 (Mid-market courses and communities); 500_plus = $500+ (Premium programs)","schema":{"type":"string","enum":["free","under_100","100_500","500_plus"]}},{"name":"operating_model","in":"query","required":true,"description":"What kind of SEO do you do it for? brand_client = Client / brand SEO (Agency or in-house); affiliate = Affiliate (Content and review sites); lead_gen = Lead generation (Service businesses, rank and rent); local = Local (Maps-led, single or multi-location); saas_ecommerce = SaaS / ecommerce (Product-led organic growth); aggressive = Aggressive / experimental (Testing on the edge of guidelines)","schema":{"type":"string","enum":["brand_client","affiliate","lead_gen","local","saas_ecommerce","aggressive"]}}],"responses":{"200":{"description":"Ranked recommendations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendationResponse"}}}},"304":{"description":"Not modified (conditional request with a matching ETag)"},"422":{"$ref":"#/components/responses/InvalidAnswers"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/comparisons":{"get":{"operationId":"compareCourses","tags":["Courses"],"summary":"Compare courses side by side","description":"Returns 2–3 courses in the order given, for side-by-side comparison.","parameters":[{"name":"courses","in":"query","required":true,"description":"2 to 3 comma-separated course slugs, e.g. ai-seo-rainmakers,traffic-think-tank.","schema":{"type":"string"}}],"responses":{"200":{"description":"The compared courses","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComparisonResponse"}}}},"304":{"description":"Not modified (conditional request with a matching ETag)"},"422":{"$ref":"#/components/responses/InvalidParameters"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/finder/questions":{"get":{"operationId":"getFinderQuestions","tags":["Reference"],"summary":"List Course Finder questions and allowed answers","description":"Returns the six questions used by recommendCourses with every allowed value and its label.","responses":{"200":{"description":"Questions and allowed values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinderQuestionsResponse"}}}},"304":{"description":"Not modified (conditional request with a matching ETag)"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/methodology":{"get":{"operationId":"getMethodology","tags":["Reference"],"summary":"Get the scoring methodology","description":"Returns the live scoring weights, adjustments, penalties, thresholds, budget bands, topic coverage scale and verification rules.","responses":{"200":{"description":"Scoring methodology","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MethodologyResponse"}}}},"304":{"description":"Not modified (conditional request with a matching ETag)"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"schemas":{"Meta":{"type":"object","properties":{"api_version":{"type":"string","const":"v1"},"canonical_url":{"type":"string","format":"uri","description":"Canonical page to link when citing."},"methodology_url":{"type":"string","format":"uri"},"openapi_url":{"type":"string","format":"uri"},"citation":{"type":"string","description":"Suggested citation text."},"last_verified_on":{"type":["string","null"],"format":"date","description":"Most recent verification date across the dataset."},"scoring_weights_updated_on":{"type":["string","null"],"format":"date"},"contains_placeholder_data":{"type":"boolean","description":"True while any course facts are unverified placeholders."},"policies":{"type":"object","additionalProperties":{"type":"string"}},"count":{"type":"integer","minimum":0}},"required":["api_version","canonical_url","methodology_url","openapi_url","citation","last_verified_on","scoring_weights_updated_on","contains_placeholder_data","policies"],"additionalProperties":false},"Course":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"provider":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":["string","null"],"format":"uri"}},"required":["name","url"],"additionalProperties":false},"page_url":{"type":"string","format":"uri","description":"This course's page on the website: the URL to cite."},"status":{"type":"string","enum":["active","inactive"],"description":"inactive = listed but not currently enrolling."},"enrolling":{"type":"boolean"},"url":{"type":["string","null"],"format":"uri","description":"The provider's own course URL (never an affiliate/tracking URL)."},"link_is_affiliate":{"type":"boolean","description":"Whether the website links this course through an affiliate link."},"description":{"type":["string","null"]},"best_for":{"type":["string","null"]},"highlights":{"type":"array","items":{"type":"string"}},"price":{"type":"object","properties":{"display":{"type":["string","null"],"description":"Price exactly as published, e.g. \"£119 / mo\"."},"amount":{"type":["number","null"]},"currency":{"type":["string","null"],"enum":["USD","GBP","EUR",null]},"type":{"type":["string","null"],"enum":["free","one_time","monthly","annual","custom",null]},"first_year_cost_usd":{"type":["number","null"],"description":"Approximate USD equivalent; used only for budget bands."},"budget_band":{"type":["string","null"],"enum":["free","under_100","100_500","500_plus",null]},"known":{"type":"boolean","description":"False when the provider doesn't publish pricing."}},"required":["display","amount","currency","type","first_year_cost_usd","budget_band","known"],"additionalProperties":false},"levels":{"type":"array","items":{"type":"string","enum":["beginner","intermediate","advanced"]}},"topic_coverage":{"type":"object","properties":{"ai_seo":{"type":"integer","minimum":0,"maximum":5},"geo":{"type":"integer","minimum":0,"maximum":5},"general_seo":{"type":"integer","minimum":0,"maximum":5},"technical_seo":{"type":"integer","minimum":0,"maximum":5},"link_building":{"type":"integer","minimum":0,"maximum":5},"content_seo":{"type":"integer","minimum":0,"maximum":5},"programmatic_seo":{"type":"integer","minimum":0,"maximum":5},"local_seo":{"type":"integer","minimum":0,"maximum":5},"affiliate_seo":{"type":"integer","minimum":0,"maximum":5},"agency":{"type":"integer","minimum":0,"maximum":5}},"required":["ai_seo","geo","general_seo","technical_seo","link_building","content_seo","programmatic_seo","local_seo","affiliate_seo","agency"],"additionalProperties":false,"description":"0 none · 1 mentioned · 2 one module · 3 substantial · 4 major focus · 5 core specialty"},"ai_geo_focus":{"type":"string","enum":["High","Medium","Low","None"]},"formats":{"type":"array","items":{"type":"string","enum":["Self-paced","Live / community","Templates \u0026 SOPs","Hands-on implementation"]}},"certification":{"type":"boolean"},"community":{"type":"string","enum":["No","Limited","Cohort only","Yes (forum)","Yes (active)"]},"updates":{"type":"string","description":"Continuous, Static, Per cohort, Unknown, or a periodic frequency such as Quarterly."},"operating_models":{"type":"array","items":{"type":"string","enum":["brand_client","affiliate","lead_gen","local","saas_ecommerce","aggressive"]}},"verification":{"type":"object","properties":{"last_verified_on":{"type":["string","null"],"format":"date"},"status":{"type":"string","enum":["fresh","review_due","stale","seriously_stale","unverified"]},"sources":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"source_type":{"type":"string","enum":["official","public_third_party","first_hand","member_verified","user_submitted"]},"label":{"type":"string"},"url":{"type":["string","null"],"format":"uri"},"verified_on":{"type":"string","format":"date"}},"required":["field","source_type","label","url","verified_on"],"additionalProperties":false}}},"required":["last_verified_on","status","sources"],"additionalProperties":false},"editorial_pick":{"oneOf":[{"type":"null"},{"type":"object","properties":{"label":{"type":["string","null"]},"reason":{"type":["string","null"]}},"required":["label","reason"],"additionalProperties":false}],"description":"Editorial award (Overall Best 2026), outside the scoring algorithm."},"placeholder_data":{"type":"boolean","description":"True when this course's facts are unverified placeholders."}},"required":["slug","name","provider","page_url","status","enrolling","url","link_is_affiliate","description","best_for","highlights","price","levels","topic_coverage","ai_geo_focus","formats","certification","community","updates","operating_models","verification","editorial_pick","placeholder_data"],"additionalProperties":false},"RecommendationResult":{"type":"object","properties":{"rank":{"type":"integer","minimum":1},"match_percent":{"type":"integer","minimum":0,"maximum":99,"description":"Fit to the answers given, not course quality."},"match_reasons":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"course":{"$ref":"#/components/schemas/Course"}},"required":["rank","match_percent","match_reasons","warnings","course"],"additionalProperties":false},"Recommendation":{"type":"object","properties":{"answers":{"type":"object","properties":{"experience":{"type":"string","enum":["beginner","intermediate","advanced"]},"objective":{"type":"string","enum":["ai_geo","general_seo","affiliate","local","links","content_programmatic","agency"]},"learning_style":{"type":"string","enum":["self_paced","live_community","templates_sops","hands_on","no_preference"]},"freshness":{"type":"string","enum":["low","important","critical"]},"budget":{"type":"string","enum":["free","under_100","100_500","500_plus"]},"operating_model":{"type":"string","enum":["brand_client","affiliate","lead_gen","local","saas_ecommerce","aggressive"]}},"required":["experience","objective","learning_style","freshness","budget","operating_model"],"additionalProperties":false},"answer_labels":{"type":"object","properties":{"experience":{"type":"string"},"objective":{"type":"string"},"learning_style":{"type":"string"},"freshness":{"type":"string"},"budget":{"type":"string"},"operating_model":{"type":"string"}},"required":["experience","objective","learning_style","freshness","budget","operating_model"],"additionalProperties":false},"match_threshold":{"type":"integer"},"result_limit":{"type":"integer"},"no_strong_match":{"type":"boolean","description":"True when no course reached the match threshold."},"results":{"type":"array","items":{"$ref":"#/components/schemas/RecommendationResult"},"maxItems":3},"human_url":{"type":"string","format":"uri","description":"The same results as a web page."},"methodology_url":{"type":"string","format":"uri"},"dataset_url":{"type":"string","format":"uri"},"citation":{"type":"string"}},"required":["answers","answer_labels","match_threshold","result_limit","no_strong_match","results","human_url","methodology_url","dataset_url","citation"],"additionalProperties":false},"AnswerOption":{"type":"object","properties":{"question":{"type":"string"},"values":{"type":"object","additionalProperties":{"type":"string"}}},"required":["question","values"],"additionalProperties":false},"Methodology":{"type":"object","properties":{"weights":{"type":"object","properties":{"objective":{"type":"integer"},"experience":{"type":"integer"},"learning_style":{"type":"integer"},"freshness":{"type":"integer"},"operating_model":{"type":"integer"},"budget":{"type":"integer"}},"required":["objective","experience","learning_style","freshness","operating_model","budget"],"additionalProperties":false},"adjustments":{"type":"object","additionalProperties":{"type":"number"}},"penalties":{"type":"object","additionalProperties":{"type":"integer"}},"freshness_fit":{"type":"object","additionalProperties":{"type":"number"}},"match_threshold":{"type":"integer"},"result_limit":{"type":"integer"},"verification_days":{"type":"object","additionalProperties":{"type":"integer"}},"budget_bands":{"type":"object","properties":{"basis":{"type":"string"},"upper_limits_usd":{"type":"object","additionalProperties":{"type":"number"}},"values":{"type":"array","items":{"type":"string","enum":["free","under_100","100_500","500_plus"]}}},"required":["basis","upper_limits_usd","values"],"additionalProperties":false},"topic_coverage_scale":{"type":"object","additionalProperties":{"type":"string"}},"methodology_url":{"type":"string","format":"uri"}},"required":["weights","adjustments","penalties","freshness_fit","match_threshold","result_limit","verification_days","budget_bands","topic_coverage_scale","methodology_url"],"additionalProperties":false},"CourseListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Course"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"],"additionalProperties":false},"CourseResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Course"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"],"additionalProperties":false},"RecommendationResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Recommendation"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"],"additionalProperties":false},"ComparisonResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"courses":{"type":"array","items":{"$ref":"#/components/schemas/Course"},"minItems":2,"maxItems":3}},"required":["courses"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"],"additionalProperties":false},"FinderQuestionsResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"questions":{"type":"object","properties":{"experience":{"$ref":"#/components/schemas/AnswerOption"},"objective":{"$ref":"#/components/schemas/AnswerOption"},"learning_style":{"$ref":"#/components/schemas/AnswerOption"},"freshness":{"$ref":"#/components/schemas/AnswerOption"},"budget":{"$ref":"#/components/schemas/AnswerOption"},"operating_model":{"$ref":"#/components/schemas/AnswerOption"}},"required":["experience","objective","learning_style","freshness","budget","operating_model"],"additionalProperties":false},"recommendations_url_template":{"type":"string"}},"required":["questions","recommendations_url_template"],"additionalProperties":false},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"],"additionalProperties":false},"MethodologyResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Methodology"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"],"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_parameters","invalid_answers","not_found","rate_limited"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"InvalidParameters":{"description":"A parameter has an unsupported value; details lists each one with its allowed values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InvalidAnswers":{"description":"One or more answers are missing or invalid; details.answer_options lists allowed values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"No course matches the slug(s).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}}},"headers":{"Retry-After":{"description":"Seconds until the rate-limit window resets","schema":{"type":"integer"}}}}}