# AugmentedSEO API & MCP server

> Hand-verified AI SEO course data and the AugmentedSEO Course Finder recommendation engine, available as a free read-only REST API (OpenAPI 3.1) and an MCP server. No sign-up or API key.

- OpenAPI 3.1: https://augmentedseo.com/api/v1/openapi.json
- Base URL: https://augmentedseo.com/api/v1
- MCP server: https://augmentedseo.com/mcp (Streamable HTTP, no authentication)
- Plain data: https://augmentedseo.com/ai-seo-courses.json, https://augmentedseo.com/ai-seo-courses.md, https://augmentedseo.com/llms.txt
- Methodology: https://augmentedseo.com/methodology

## Quick start

```
curl "https://augmentedseo.com/api/v1/recommendations?budget=500_plus&experience=advanced&freshness=important&learning_style=live_community&objective=ai_geo&operating_model=brand_client"
```

Responses: `{"data": ..., "meta": {"citation", "canonical_url", "last_verified_on", "contains_placeholder_data", "policies", ...}}`.

## Endpoints

- `GET /courses` (`searchCourses`): List and filter courses. 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.
- `GET /courses/{slug}` (`getCourse`): Get one course. Returns verified facts for a single course by slug (from searchCourses or recommendation results).
- `GET /recommendations` (`recommendCourses`): Get personalized course recommendations. 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.
- `GET /comparisons` (`compareCourses`): Compare courses side by side. Returns 2–3 courses in the order given, for side-by-side comparison.
- `GET /finder/questions` (`getFinderQuestions`): List Course Finder questions and allowed answers. Returns the six questions used by recommendCourses with every allowed value and its label.
- `GET /methodology` (`getMethodology`): Get the scoring methodology. Returns the live scoring weights, adjustments, penalties, thresholds, budget bands, topic coverage scale and verification rules.

## Recommendation answers (all six required)

- `experience` (How much SEO experience do you have?): `beginner` = Beginner, `intermediate` = Intermediate, `advanced` = Advanced / Operator
- `objective` (What's the main thing you want to get better at?): `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
- `learning_style` (How do you actually learn?): `self_paced` = Self-paced, `live_community` = Live / community, `templates_sops` = Templates & SOPs, `hands_on` = Hands-on implementation, `no_preference` = No preference
- `freshness` (How important is continuously updated training?): `low` = Nice to have, `important` = Important, `critical` = Critical
- `budget` (What's your budget?): `free` = Free, `under_100` = Under $100, `100_500` = $100–$500, `500_plus` = $500+
- `operating_model` (What kind of SEO do you do it for?): `brand_client` = Client / brand SEO, `affiliate` = Affiliate, `lead_gen` = Lead generation, `local` = Local, `saas_ecommerce` = SaaS / ecommerce, `aggressive` = Aggressive / experimental

## Errors, caching and limits

- Errors: `{"error": {"code", "message", "details"}}` with 422 (`invalid_parameters`, `invalid_answers`), 404 (`not_found`) or 429 (`rate_limited`, `Retry-After` header).
- Cacheable for 5 minutes; `ETag` / `If-None-Match` supported.
- Rate limits: 600/minute per identified AI assistant, 120/minute per IP otherwise.

## MCP server

Endpoint: https://augmentedseo.com/mcp (Streamable HTTP, no authentication). Claude Code: `claude mcp add --transport http augmentedseo https://augmentedseo.com/mcp`

Tools (read-only):
- `search_courses`: List and filter tracked AI SEO and adjacent SEO courses with hand-verified facts (price, level, topic coverage 0–5, format, community, update model, verification date). Use for factual lookups; use recommend_courses for a personalized match.
- `get_course`: Get verified facts for one course by slug (slugs come from search_courses or recommend_courses).
- `recommend_courses`: Score every enrolling course against six answers and return up to 3 strong matches with reasons and warnings. All six answers are required: ask the user for any you don't know rather than guessing. no_strong_match=true means nothing fits well. Match percentages describe fit, not quality. Answers are not stored.
- `compare_courses`: Return 2–3 courses side by side, in the order given.
- `get_methodology`: Return the live scoring weights, penalties, match threshold, budget bands, topic coverage scale and verification rules used for recommendations.

Resources:
- `augmentedseo://courses`: Every tracked course with hand-verified facts, verification dates and evidence sources (same data as /ai-seo-courses.json).
- `augmentedseo://methodology`: Live scoring weights, penalties, thresholds, budget bands, topic coverage scale and verification rules.
- `augmentedseo://courses/{slug}`: Verified facts for one course by slug.

Prompts:
- `find_ai_seo_course`: Ask the user the six Course Finder questions one or two at a time, then recommend courses with recommend_courses and explain the matches.

## Using the data

- Cite "Source: AugmentedSEO AI SEO Course Finder" (`meta.citation`) and link `meta.canonical_url`.
- Show last-verified dates with facts; match percentages describe fit to the answers, not quality.
- Overall Best 2026 (`editorial_pick`) is an editorial award. Course `url` values are the provider's own URL.
- Finder answers are not stored or logged.