substack-api

The Substack API library is organized into several specialized modules for interacting with different parts of the Substack platform:

• User: Access to Substack user profiles and subscriptions.
• Newsletter: Access to Substack publications, posts, and podcasts.
• Post: Access to individual Substack post content and metadata.
• Category: Discovery of newsletters by category.
• Chat: Access to publication subscriber chats and threads.
• SubstackAuth: Authentication for accessing paywalled content.

When using the library, you will encounter several consistent patterns across most classes:

1. Initialization: Objects are typically instantiated by providing an identifier such as a URL or a username.
2. Data Retrieval: Classes provide methods specifically designed to fetch data from the Substack API.
3. Caching: The library implements caching to minimize unnecessary API requests and improve performance.
4. Force Refresh: To bypass the cache and fetch fresh data from the API, most methods accept a force_refresh parameter.

The library caches API responses by default to minimize requests. To bypass the cache and fetch fresh data from the server, pass force_refresh=True to relevant methods like get_metadata() or get_raw_data().

# Force refresh of post data
post.get_metadata(force_refresh=True)

# Force refresh of user data
user.get_raw_data(force_refresh=True)

The chat module follows a hierarchical structure to navigate Substack community discussions:

1. Chat: The entry point. It represents the entire chat room for a specific publication_id. You use this to discover threads.
2. ChatThread: A specific discussion topic within a Chat. It contains the original post and metadata like comment_count.
3. ChatMessage: The individual units of conversation (replies) within a ChatThread.

To navigate, you typically instantiate a Chat, call get_threads() to get ChatThread objects, and then call get_messages() on a thread to get ChatMessage objects.

The library is organized around several main classes that represent different entities in the Substack ecosystem:

• User: Represents a Substack user profile.
• Newsletter: Represents a Substack publication.
• Post: Represents an individual post on Substack.
• Category: Represents a Substack category of newsletters.
• Chat: Represents a publication's subscriber chat.
• SubstackAuth: Handles authentication for accessing paywalled content.

To access paywalled content that you have written or paid for, you must provide session cookies in a JSON format. Use the SubstackAuth class and pass it to Newsletter or Post instances.

from substack_api import Newsletter, Post, SubstackAuth

# Set up authentication with your cookies
auth = SubstackAuth(cookies_path="path/to/your/cookies.json")

# Use authentication with newsletters
newsletter = Newsletter("https://example.substack.com", auth=auth)
posts = newsletter.get_posts(limit=5)  # Can now access paywalled posts

# Use authentication with individual posts
post = Post("https://example.substack.com/p/paywalled-post", auth=auth)
content = post.get_content()  # Can now access paywalled content

# Check if a post is paywalled
if post.is_paywalled():
    print("This post requires a subscription")

The simplest way to install the Substack API library is using pip. Ensure you have Python 3.12 or higher installed.

pip install substack-api

To install the library from the source repository, clone the repository and install it in editable mode using pip.

git clone https://github.com/nhagar/substack_api.git
cd substack_api
pip install -e .

To access content behind a paywall, you must provide a SubstackAuth object (initialized with a cookies_path) when creating the Post instance.

Workflow

1. Check if the post is paywalled using is_paywalled().
2. If it is, instantiate SubstackAuth using your cookies.
3. Create a new Post instance passing the auth object.
4. Call get_content() to retrieve the HTML.

from substack_api import Post, SubstackAuth

auth = SubstackAuth(cookies_path="cookies.json")
authenticated_post = Post("https://example.substack.com/p/paywalled-post", auth=auth)
content = authenticated_post.get_content()

Installing the substack-api package automatically installs the substack command-line interface (CLI). You can verify the installation by running the help command or starting the quickstart guide.

substack --help
substack quickstart