Posted on May 8 • Originally published at developer-service.blog

Save Hours Managing Ghost with These Python Scripts

I run the blog at Developer-Service.blog with a self-hosted Ghost instance.

As much as I love Ghost and its editor, I've encountered a handful of limitations in the Ghost Admin interface that have slowed me down.

Things like:

Re-categorizing posts in bulk.
Quickly searching posts by title.
And many others...

Doing some of these things manually, one by one, through the Ghost admin panel wasn’t just inefficient—it was also error-prone.

So I wrote three small but powerful Python scripts that leverage the Ghost Admin API using JWT authentication.

These scripts saved me hours of clicking and let me manage my content programmatically, with zero guesswork.

GitHub repository for all the scripts: https://github.com/nunombispo/GhostContentAPI

SPONSORED By Python's Magic Methods - Beyond init and str

This book offers an in-depth exploration of Python's magic methods, examining the mechanics and applications that make these features essential to Python's design.

Get the eBook

📦 Setup: Ghost Admin API + Python Environment

Before running the scripts, here’s what you need:

Create an Integration in Ghost Admin:

Go to Settings → Integrations → Add custom integration.
Note the Admin API Key (it looks like XXXXX:YYYYYYYYYYYYY...),
Keep in mind that the API URL for your Ghost site is normally your blog URL.

Create a .env file for your credentials:

GHOST_URL=https://your-blog.com GHOST_ADMIN_API_KEY=YOUR_KEY_ID:YOUR_SECRET

Install dependencies:

pip install python-dotenv pyjwt requests

Every script uses this shared boilerplate for JWT auth and getting the full API URL:

def get_ghost_token(): """ Generate JWT token for Ghost Admin API authentication. Returns: str: JWT token for API authentication Raises: ValueError: If GHOST_ADMIN_API_KEY is not found in environment variables Exception: If token generation fails """ try: # Get API key from environment  key = os.getenv('GHOST_ADMIN_API_KEY') if not key: raise ValueError("GHOST_ADMIN_API_KEY not found in environment variables") # Split the key into ID and SECRET  id, secret = key.split(':') # Prepare header and payload  iat = int(datetime.now().timestamp()) header = {'alg': 'HS256', 'typ': 'JWT', 'kid': id} payload = { 'iat': iat, 'exp': iat + 5 * 60, # Token expires in 5 minutes  'aud': '/admin/' } # Create the token  token = jwt.encode( payload, bytes.fromhex(secret), algorithm='HS256', headers=header ) return token except Exception as e: logger.error(f"Failed to generate Ghost token: {str(e)}") raise def get_ghost_api_url(): """ Get the Ghost Admin API URL from environment variables. Returns: str: Complete Ghost Admin API URL Raises: ValueError: If GHOST_URL is not found in environment variables """ base_url = os.getenv('GHOST_URL') if not base_url: raise ValueError("GHOST_URL not found in environment variables") # Remove trailing slash if present  base_url = base_url.rstrip('/') return f"{base_url}/ghost/api/admin"

🔒 Archiving Older Posts for Paid Members

I wanted to convert older posts - anything published before this year - into exclusive content for paying subscribers.

This script does exactly that:

📁 Script: update_posts_to_paid.py

🔍 Filter: posts before Jan 1 this year, not already "paid"

🔄 Change: visibility → paid

How it works:

Here is the update posts function used in that script:

def update_posts_to_paid(): """ Update non-paid posts from previous years to paid status. This function: 1. Retrieves all posts that are not paid and were published before the current year 2. Updates each post's visibility to 'paid' 3. Maintains the post's updated_at timestamp to prevent conflicts Returns: int: Number of successfully updated posts Raises: Exception: If any error occurs during the update process """ try: # Get authentication token and API URL  token = get_ghost_token() api_url = get_ghost_api_url() # Set up headers  headers = { 'Authorization': f'Ghost {token}', 'Content-Type': 'application/json', 'Accept-Version': 'v5.0' } # Calculate the start of the current year  current_year = datetime.now().year start_of_current_year = f"{current_year}-01-01T00:00:00Z" # Get posts from previous years that are not paid  posts_url = f"{api_url}/posts/" response = requests.get( posts_url, headers=headers, params={ 'limit': 'all', 'filter': f'visibility:-paid+published_at:<{start_of_current_year}' } ) response.raise_for_status() posts = response.json()['posts'] logger.info(f"Found {len(posts)} posts from previous years that are not paid") # Update each post to paid status  updated_count = 0 for post in posts: try: # Get the latest version of the post to ensure we have the current updated_at  post_url = f"{api_url}/posts/{post['id']}/" post_response = requests.get(post_url, headers=headers) post_response.raise_for_status() current_post = post_response.json()['posts'][0] # Create the update data  update_url = f"{api_url}/posts/{post['id']}/" update_data = { 'posts': [{ 'id': post['id'], 'visibility': 'paid', 'updated_at': current_post['updated_at'] }] } # Update the post to paid status  update_response = requests.put( update_url, headers=headers, json=update_data ) update_response.raise_for_status() updated_count += 1 logger.info(f"Updated post: {post['title']}") except Exception as e: logger.error(f"Failed to update post {post['title']}: {str(e)}") continue logger.info(f"Successfully updated {updated_count} posts to paid status") return updated_count except Exception as e: logger.error(f"An error occurred: {str(e)}") raise

Ghost exposes a query language called NQL for filtering API results - see the Content API docs for full details.

Its syntax works much like filters in Gmail, GitHub, or Slack: you specify a field and a value separated by a colon.

A filter expression takes the form property:operator_value where:

property is the field path you want to query,
operator (optional) defines the comparison (a bare : acts like =), and
value is the term you’re matching against.

So, for my case, I use these filters:

params={ 'limit': 'all', 'filter': f'visibility:-paid+published_at:<{start_of_current_year}' }

Which represents not paid (-paid) and published before the start of the current year. In this case, I am getting all the records without pagination (limit = all).

Then for each post, I get its details:

# Get the latest version of the post to ensure we have the current updated_at post_url = f"{api_url}/posts/{post['id']}/" post_response = requests.get(post_url, headers=headers) post_response.raise_for_status() current_post = post_response.json()['posts'][0]

This is because the update API below requires a updated_at field for collision detection. In my case, I don't want to change the update date.

And updating is done with a PUT method by which the body is:

'posts': [{ 'id': post['id'], 'visibility': 'paid', 'updated_at': current_post['updated_at'] }]

This updates all the previous posts to paid, keeping the update date.

🧱 Moving Public Posts This Year to “Members Only”

Another update that I wanted to do in bulk was to update some posts published this year to be members only and that were still public.

I needed to fix that, but only for current-year content, not the archive.

📁 Script: update_posts_member.py

🔍 Filter: published this year + visibility = "public"

🔄 Change: visibility → members

Why?

I offer a “members only” tier that’s free with signup, and I want this year’s posts to be accessible only after registration.

Here is the update posts function used in that script:

def update_posts_to_paid(): """ Update public posts from the current year to members-only status. This function: 1. Retrieves all public posts published in the current year 2. Updates each post's visibility to 'members' 3. Maintains the post's updated_at timestamp to prevent conflicts Returns: int: Number of successfully updated posts Raises: Exception: If any error occurs during the update process """ try: # Get authentication token and API URL  token = get_ghost_token() api_url = get_ghost_api_url() # Set up headers  headers = { 'Authorization': f'Ghost {token}', 'Content-Type': 'application/json', 'Accept-Version': 'v5.0' } # Calculate the start of the current year  current_year = datetime.now().year start_of_current_year = f"{current_year}-01-01T00:00:00Z" # Get posts from current year that are public  posts_url = f"{api_url}/posts/" response = requests.get( posts_url, headers=headers, params={ 'limit': 'all', 'filter': f'visibility:public+published_at:>={start_of_current_year}' } ) response.raise_for_status() posts = response.json()['posts'] logger.info(f"Found {len(posts)} posts from current year that are public") # Update each post to paid status  updated_count = 0 for post in posts: try: # Get the latest version of the post to ensure we have the current updated_at  post_url = f"{api_url}/posts/{post['id']}/" post_response = requests.get(post_url, headers=headers) post_response.raise_for_status() current_post = post_response.json()['posts'][0] # Create the update data  update_url = f"{api_url}/posts/{post['id']}/" update_data = { 'posts': [{ 'id': post['id'], 'visibility': 'members', 'updated_at': current_post['updated_at'] }] } # Update the post to paid status  update_response = requests.put( update_url, headers=headers, json=update_data ) update_response.raise_for_status() updated_count += 1 logger.info(f"Updated post: {post['title']}") except Exception as e: logger.error(f"Failed to update post {post['title']}: {str(e)}") continue logger.info(f"Successfully updated {updated_count} posts to members status") return updated_count except Exception as e: logger.error(f"An error occurred: {str(e)}") raise

For the filters, this time I used:

params={ 'limit': 'all', 'filter': f'visibility:public+published_at:>={start_of_current_year}' }

Which represents public and published after (or at) the start of the current year. I am getting again all the records without pagination (limit = all).

Then, to update:

'posts': [{ 'id': post['id'], 'visibility': 'members', 'updated_at': current_post['updated_at'] }]

This updates all the previous posts to members, keeping the update date. It is not shown here, but just like before, I get the updated_at from each post.

🔍 Searching Posts + Getting Direct Edit Links

This was a major pain point for me.

I often need to jump into Ghost to edit an old post, but Ghost has no “search posts by title” function.

📁 Script: post_search.py

🔎 Input: a search term

📋 Output: list of matching posts with direct edit URLs

Let's see the function that I used:

def search_posts(search_term): """ Search for posts in Ghost that match the given search term in their title. This function: 1. Searches for posts with titles containing the search term 2. Displays detailed information about each matching post 3. Provides both public URL and admin edit URL for each post Args: search_term (str): The term to search for in post titles Returns: list: List of matching post objects from the Ghost API Raises: Exception: If any error occurs during the search process """ try: # Get authentication token and API URL  token = get_ghost_token() api_url = get_ghost_api_url() # Set up headers  headers = { 'Authorization': f'Ghost {token}', 'Content-Type': 'application/json', 'Accept-Version': 'v5.0' } # Search for posts  posts_url = f"{api_url}/posts/" response = requests.get( posts_url, headers=headers, params={ 'limit': 'all', 'filter': f"title:~'{search_term}'" } ) response.raise_for_status() posts = response.json()['posts'] logger.info(f"Found {len(posts)} posts matching search term: '{search_term}'") # Display matching posts  if posts: print("\nMatching Posts:") print("-" * 50) for post in posts: edit_url = get_edit_url(post['id']) print(f"Title: {post['title']}") print(f"Published: {post['published_at']}") print(f"Status: {post['status']}") print(f"Visibility: {post['visibility']}") print(f"URL: {post['url']}") print(f"Edit URL: {edit_url}") print("-" * 50) else: print(f"\nNo posts found matching: '{search_term}'") return posts except Exception as e: logger.error(f"An error occurred: {str(e)}") raise

Similar to filtering the posts by visibility, the Ghost Admin API also allows filtering by title:

params={ 'limit': 'all', 'filter': f"title:~'{search_term}'" }

The ~ means that the title contains the search_term. So it doesn't need to be an exact match.

This will output something like this, in my case, searching for jinja2:

Enter search term: jinja2 2025-05-02 15:54:26,790 - INFO - Found 2 posts matching search term: 'jinja2' Matching Posts: -------------------------------------------------- Title: How to Build Dynamic Frontends with FastAPI and Jinja2 published: 2025-02-21T07:40:38.000Z Status: published Visibility: members URL: https://developer-service.blog/how-to-build-dynamic-frontends-with-fastapi-and-jinja2/ Edit URL: https://xxxxxx.xxx/ghost/#/editor/post/69f91be4d20f7e/ -------------------------------------------------- Title: Creating a Web Application for Podcast Search using FastAPI, Jinja2, and Podcastindex.org published: 2024-06-06T09:12:23.000Z Status: published Visibility: paid URL: https://developer-service.blog/creating-a-web-application-for-podcast-search-using-fastapi-jinja2-and-podcastindex-org/ Edit URL: https://xxxxxx.xxx/ghost/#/editor/post/125171af2e15e59/ --------------------------------------------------

This script saves me endless time. I can search by partial title, copy the direct Ghost editor link, and jump straight into editing.

✅ Summary

With just three small scripts, I improved tremendously my entire editorial workflow:

Each script takes just a few seconds to run, and I now have more control over my Ghost posts.

If you’re running a content-heavy site on Ghost or offering tiered memberships, I highly recommend building your own admin tools like this.

Ghost’s API makes it easy, and Python makes it powerful.