Substack API. Publications, posts and Notes as JSON.

Yes. Social Fetch has 26 Substack routes under /v1/substack covering publications, archives, post bodies, sitemaps, in-publication search, recommendations, feeds, posts, comments, reactors, restackers, reader profiles, Notes, subscriptions, search, categories, the explore feed and the publication directory. Authenticate with your Social Fetch API key in x-api-key.

Publication metadata takes a numeric id (89120), a Substack subdomain (astralcodexten), a host (www.astralcodexten.com) or a full publication URL. The archive, bulk posts, sitemap, in-publication search and feed routes take a subdomain, host or URL; a numeric id returns a 400 there. Recommendations accept a numeric id or a host. A host or URL is the safest choice when the publication uses a custom domain.

Free posts return bodyHtml with the whole body. Paid posts return the preview the publication makes public and set bodyIsPreview to true, so a preview is never mistaken for the full text. Use publication.posts.bodies.list to pull up to 50 posts with their bodies per cursor page.

Publication search sometimes cannot be answered reliably. The request then returns 503 and is not charged, rather than an empty list that could be mistaken for no matches. search.profiles and categories.publications.list are the dependable ways to find a publication. Podcast search follows the same rule.

post.comments.list returns the whole nested tree in comments, the number of top-level and nested nodes in returnedCount, and commentsHidden true when a paid post does not serve comments publicly. Use the post URL, not a numeric id. When more than 5,000 nodes are present the list is cut and truncated is true.

Archive listings serve up to 23 rows and page by the page.nextCursor each response carries; a page above 0 returns a 400. Bulk posts, Notes, subscriptions, restacks, podcast search and the explore feed also use an opaque cursor. In-publication post search, profile search, publication search and category leaderboards use a page number; profile and publication search run from page 0 to page 3, in-publication post search runs to page 20, and a category leaderboard runs from page 0 to page 20. A page past the last one returns an empty list with hasMore: false. Top search uses a cursor. Every list reports page.hasMore and the next value.

profile.get returns name, handle, bio, photoUrl, follower and subscriber labels, badges, links, publications with their role and primary flag, public subscriptions, and counts. profile.notes.list returns the Notes and replies history, and profile.subscriptions.list returns the publications that person shows publicly.

Yes. categories.list returns top-level categories with subcategories and the recommended view. categories.publications.list returns one page of a leaderboard for a category id, ranking all, paid or trending, with 25 publications a page, pages 0 to 20. The global directory route lists publication subdomains, one file of about 16,000 at a time and up to 5,000 entries a page.

publication.posts.index.list splits the sitemap into posts (only /p/{slug} URLs) and pages (everything else, such as /archive and /about). Every row carries kind, url, slug, lastModified and changeFrequency, and publicationId is filled when the publication is known.

No. HTTP 200 means the request finished. Check data.lookupStatus: not_found means the publication, post, reader or note does not exist, and restricted means the publication exists but does not serve that surface publicly.

Yes. Every Substack route is reachable from the hosted MCP server and through Ask (POST /v1/ask) in plain English, with the same credit metering as REST. Use the typed routes for production jobs.