Substack Categories API
The category tree and Substack's recommended view, with the ids the leaderboard route needs.
GET /v1/substack/categories1 credit Failed requests are free
About this endpoint
GET /v1/substack/categories lists Substack categories. data.categories[] carries id, name, canonicalName, slug, active, rank, parentTagId, emoji, leaderboardDescription, deprecated, type, leaderboardEnabled, createdAt, updatedAt and subcategories[].
data.recommended is Substack's recommended category view, with categoryId, ranking, hasMore, categories, publications and homepageFeaturedPublications. It is null when it was temporarily unavailable, and categories is still returned. Use a categories[].id with categories.publications.list to read a leaderboard.
Substack Categories API FAQ
Where do I get a category id?
From data.categories[].id or data.recommended.categoryId. The leaderboard route takes that numeric id.
Why is recommended null?
When the recommended view is temporarily unavailable, recommended is null and the category tree is still returned.
Are subcategories nested?
Yes, one level deep in subcategories. The public schema keeps them non-recursive for the OpenAPI document.
How many credits does a categories lookup cost?
Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged: that field is the billing source of truth.
Other Substack endpoints
- PublicationGET /v1/substack/publications/{publication}
- PostsGET /v1/substack/publications/{publication}/posts
- Post bodiesGET /v1/substack/publications/{publication}/posts/bodies
- Post indexGET /v1/substack/publications/{publication}/posts/index
- Search postsGET /v1/substack/publications/{publication}/posts/search
- RecommendationsGET /v1/substack/publications/{publication}/recommendations
- Publication feedGET /v1/substack/publications/{publication}/feed
- PostGET /v1/substack/posts/{post}