{"openapi":"3.0.3","info":{"title":"Medium API (ReefAPI)","version":"0.2.0","description":"Medium API scraper — Medium.com articles (full text, HTML & markdown), author profiles, publications, responses, tags and search, no account needed Call POST /medium/v1/{action} with an x-api-key header; every response is the { ok, data, meta, error } envelope.","contact":{"name":"ReefAPI","url":"https://reefapi.com/medium-api","email":"support@reefapi.com"},"license":{"name":"ReefAPI Terms","url":"https://reefapi.com/terms"},"termsOfService":"https://reefapi.com/terms"},"externalDocs":{"description":"Medium API documentation","url":"https://reefapi.com/docs/medium"},"servers":[{"url":"https://api.reefapi.com"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"medium","description":"Medium API scraper — Medium.com articles (full text, HTML & markdown), author profiles, publications, responses, tags and search, no account needed"}],"paths":{"/medium/v1/user":{"post":{"operationId":"medium_user","summary":"Public Medium user profile by username.","description":"Public Medium user profile by username.","tags":["medium"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"string","example":"dhh","description":"Medium username, with or without the leading @ (the name in medium.com/@<user>)."}},"required":["user"]},"example":{"user":"dhh"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/medium/v1/user_id":{"post":{"operationId":"medium_user_id","summary":"Resolve username to Medium userId.","description":"Resolve username to Medium userId.","tags":["medium"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"string","example":"dhh","description":"Medium username, with or without the leading @ (the name in medium.com/@<user>)."}},"required":["user"]},"example":{"user":"dhh"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/medium/v1/user_articles":{"post":{"operationId":"medium_user_articles","summary":"An author's published articles, newest first, with deep pagination.","description":"An author's published articles, newest first, with deep pagination.","tags":["medium"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"string","example":"dhh","description":"Medium username, with or without the leading @ (the name in medium.com/@<user>)."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10,"example":10,"description":"Max items to return (1-50). Larger values are clamped to 50."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's next_cursor. Omit for page one."}},"required":["user"]},"example":{"user":"dhh"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/medium/v1/user_top_articles":{"post":{"operationId":"medium_user_top_articles","summary":"User articles sorted by clap count from profile references.","description":"User articles sorted by clap count from profile references.","tags":["medium"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"string","example":"dhh","description":"Medium username, with or without the leading @ (the name in medium.com/@<user>)."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":25,"example":25,"description":"Max items to return (1-50). Larger values are clamped to 50."}},"required":["user"]},"example":{"user":"dhh"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/medium/v1/article":{"post":{"operationId":"medium_article","summary":"Article metadata by url or id.","description":"Article metadata by url or id.","tags":["medium"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","example":"https://medium.com/@dhh/some-article-0123456789ab","description":"Full article URL (alternative to id)."},"id":{"type":"string","example":"0123456789ab","description":"Article post id — the 12-char hex at the end of an article URL. Provide id OR url."}}},"example":{"url":"https://medium.com/signal-v-noise/reconsider-41adf356857f"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/medium/v1/article_content":{"post":{"operationId":"medium_article_content","summary":"Article plain-text body from bodyModel paragraphs.","description":"Article plain-text body from bodyModel paragraphs.","tags":["medium"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","example":"https://medium.com/@dhh/some-article-0123456789ab","description":"Full article URL (alternative to id)."},"id":{"type":"string","example":"0123456789ab","description":"Article post id — the 12-char hex at the end of an article URL. Provide id OR url."}}},"example":{"url":"https://medium.com/signal-v-noise/reconsider-41adf356857f"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/medium/v1/article_html":{"post":{"operationId":"medium_article_html","summary":"Article HTML body from bodyModel paragraphs.","description":"Article HTML body from bodyModel paragraphs.","tags":["medium"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","example":"https://medium.com/@dhh/some-article-0123456789ab","description":"Full article URL (alternative to id)."},"id":{"type":"string","example":"0123456789ab","description":"Article post id — the 12-char hex at the end of an article URL. Provide id OR url."}}},"example":{"url":"https://medium.com/signal-v-noise/reconsider-41adf356857f"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/medium/v1/article_markdown":{"post":{"operationId":"medium_article_markdown","summary":"Article markdown body from bodyModel paragraphs.","description":"Article markdown body from bodyModel paragraphs.","tags":["medium"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","example":"https://medium.com/@dhh/some-article-0123456789ab","description":"Full article URL (alternative to id)."},"id":{"type":"string","example":"0123456789ab","description":"Article post id — the 12-char hex at the end of an article URL. Provide id OR url."}}},"example":{"url":"https://medium.com/signal-v-noise/reconsider-41adf356857f"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/medium/v1/article_responses":{"post":{"operationId":"medium_article_responses","summary":"Public responses/comments for an article.","description":"Public responses/comments for an article.","tags":["medium"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","example":"https://medium.com/@dhh/some-article-0123456789ab","description":"Full article URL (alternative to id)."},"id":{"type":"string","example":"0123456789ab","description":"Article post id — the 12-char hex at the end of an article URL. Provide id OR url."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10,"example":10,"description":"Max items to return (1-50). Larger values are clamped to 50."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's next_cursor. Omit for page one."}}},"example":{"url":"https://medium.com/signal-v-noise/reconsider-41adf356857f","limit":10}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/medium/v1/publication":{"post":{"operationId":"medium_publication","summary":"Publication/collection metadata by slug.","description":"Publication/collection metadata by slug.","tags":["medium"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","example":"better-programming","description":"Publication slug — the path segment in medium.com/<slug> (or its custom-domain handle)."}},"required":["slug"]},"example":{"slug":"towards-data-science"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/medium/v1/publication_id":{"post":{"operationId":"medium_publication_id","summary":"Resolve publication slug to collection id.","description":"Resolve publication slug to collection id.","tags":["medium"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","example":"better-programming","description":"Publication slug — the path segment in medium.com/<slug> (or its custom-domain handle)."}},"required":["slug"]},"example":{"slug":"towards-data-science"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/medium/v1/publication_articles":{"post":{"operationId":"medium_publication_articles","summary":"A publication's articles, newest first, with deep pagination.","description":"A publication's articles, newest first, with deep pagination.","tags":["medium"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","example":"better-programming","description":"Publication slug — the path segment in medium.com/<slug> (or its custom-domain handle)."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10,"example":10,"description":"Max items to return (1-50). Larger values are clamped to 50."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's next_cursor. Omit for page one."}},"required":["slug"]},"example":{"slug":"towards-data-science","limit":10}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/medium/v1/tag":{"post":{"operationId":"medium_tag","summary":"Latest posts for a topic tag (the tag/topic feed).","description":"Latest posts for a topic tag (the tag/topic feed).","tags":["medium"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tag":{"type":"string","example":"python","description":"Medium topic tag slug (e.g. python, machine-learning)."},"limit":{"type":"integer","minimum":1,"maximum":25,"default":10,"example":10,"description":"Max items to return (1-25). Larger values are clamped to 25."}},"required":["tag"]},"example":{"tag":"python"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/medium/v1/search_users":{"post":{"operationId":"medium_search_users","summary":"Look up an author by exact username","description":"Look up an author by exact username. (Medium gates fuzzy people-search behind a logged-in JS app, so this resolves q as a username and returns that profile.)","tags":["medium"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","example":"python","description":"Search term."}},"required":["q"]},"example":{"q":"dhh"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/medium/v1/search_publications":{"post":{"operationId":"medium_search_publications","summary":"Look up a publication by exact slug","description":"Look up a publication by exact slug. (Fuzzy publication search is login/JS-gated on Medium, so this resolves q as a publication slug and returns that publication.)","tags":["medium"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","example":"python","description":"Search term."}},"required":["q"]},"example":{"q":"towards-data-science"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/medium/v1/search_tags":{"post":{"operationId":"medium_search_tags","summary":"Check whether a topic tag exists and is active on Medium (resolves q as a tag slug).","description":"Check whether a topic tag exists and is active on Medium (resolves q as a tag slug).","tags":["medium"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","example":"python","description":"Search term."}},"required":["q"]},"example":{"q":"python"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/medium/v1/followers":{"post":{"operationId":"medium_followers","summary":"An author's followers (paginated)","description":"An author's followers (paginated). Identify the author by 'user' or 'user_id'.","tags":["medium"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"string","example":"dhh","description":"Medium username (with/without @). Provide user OR user_id."},"user_id":{"type":"string","example":"abc123def456","description":"Medium numeric/hash user id (a profile's user_id). Provide user_id OR user."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10,"example":10,"description":"Max items to return (1-50). Larger values are clamped to 50."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's next_cursor. Omit for page one."}}},"example":{"user":"dhh","limit":10}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/medium/v1/following":{"post":{"operationId":"medium_following","summary":"The authors a user follows (paginated)","description":"The authors a user follows (paginated). Identify the user by 'user' or 'user_id'.","tags":["medium"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"string","example":"dhh","description":"Medium username (with/without @). Provide user OR user_id."},"user_id":{"type":"string","example":"abc123def456","description":"Medium numeric/hash user id (a profile's user_id). Provide user_id OR user."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10,"example":10,"description":"Max items to return (1-50). Larger values are clamped to 50."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's next_cursor. Omit for page one."}}},"example":{"user":"dhh","limit":10}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/medium/v1/list":{"post":{"operationId":"medium_list","summary":"Reading list metadata and articles from public list page HTML","description":"Reading list metadata and articles from public list page HTML. Provide the full list 'url', or 'id' together with 'user'.","tags":["medium"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"38f9e0f9bea6","description":"Reading-list id (the trailing id in a list URL). Provide with 'user', or instead pass the full list 'url'."},"url":{"type":"string","example":"https://medium.com/@dhh/list/my-list-abcdef012345","description":"Full reading-list URL (alternative to user + id)."},"user":{"type":"string","example":"dhh","description":"List owner's username (with/without @; also accepted as 'username'). Combine with id, or pass the full url."},"slug":{"type":"string","example":"my-reading-list","description":"Optional list slug (the human-readable part of a list URL)."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":25,"example":25,"description":"Max items to return (1-50). Larger values are clamped to 50."}}},"example":{"url":"https://medium.com/@dhh/list/my-list-abcdef012345"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/medium/v1/search_articles":{"post":{"operationId":"medium_search_articles","summary":"Search Medium articles by keyword — returns matching articles with title, URL and publication details from medium.com.","description":"Search Medium articles by keyword — returns matching articles with title, URL and publication details from medium.com.","tags":["medium"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","example":"python","description":"Search term."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10,"example":10,"description":"Max items to return (1-50). Larger values are clamped to 50."},"cursor":{"type":"string","description":"Pagination cursor from a previous response's next_cursor. Omit for page one."}},"required":["q"]},"example":{"q":"dhh"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Envelope":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"},"data":{"description":"Action result (shape varies per action)"},"meta":{"type":"object","description":"api, endpoint, mode, latency_ms, record_count, completeness_pct"},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}