aioghost

Async Python client for the Ghost Admin API.

Installation

pip install aioghost

Quick Start

import asyncio
from aioghost import GhostAdminAPI

async def main():
    async with GhostAdminAPI(
        api_url="https://your-site.ghost.io",
        admin_api_key="your-admin-api-key"
    ) as api:
        # Get site info
        site = await api.get_site()
        print(f"Site: {site['title']}")

        # Get member counts
        members = await api.get_members_count()
        print(f"Total members: {members['total']}")
        print(f"Paid members: {members['paid']}")

        # Get MRR
        mrr = await api.get_mrr()
        print(f"MRR: ${mrr.get('usd', 0) / 100:.2f}")

asyncio.run(main())

Features

Fully async — Built on aiohttp for non-blocking I/O
Type hints — Full type annotations for IDE support
Context manager — Automatic session cleanup with async with
Parallel requests — Uses asyncio.gather() for efficient batching
Proper exceptions — Typed exceptions for different error cases

API Coverage

Endpoint	Method
Site info	`get_site()`
Posts count	`get_posts_count()`
Latest post	`get_latest_post()`
Members count	`get_members_count()`
MRR	`get_mrr()`
Newsletters	`get_newsletters()`
Latest email	`get_latest_email()`
Comments count	`get_comments_count()`
Tiers	`get_tiers()`
ActivityPub stats	`get_activitypub_stats()`
Webhooks	`create_webhook()`, `delete_webhook()`
Validate credentials	`validate_credentials()`

Getting Your Admin API Key

Log in to your Ghost Admin panel
Go to Settings → Integrations
Click Add custom integration
Copy the Admin API Key (format: id:secret)

Exceptions

from aioghost import (
    GhostError,           # Base exception
    GhostAuthError,       # Invalid API key
    GhostConnectionError, # Network error
    GhostNotFoundError,   # 404 response
    GhostValidationError, # Invalid request
)

Passing Your Own Session

If you want to reuse an existing aiohttp.ClientSession:

import aiohttp
from aioghost import GhostAdminAPI

async def main():
    async with aiohttp.ClientSession() as session:
        api = GhostAdminAPI(
            api_url="https://your-site.ghost.io",
            admin_api_key="your-key",
            session=session,
        )
        site = await api.get_site()
        # Session is NOT closed when api goes out of scope

Copyright & license

Copyright (c) 2013-2026 Ghost Foundation - Released under the MIT license. Ghost and the Ghost Logo are trademarks of Ghost Foundation Ltd. Please see our trademark policy for info on acceptable usage.

Development Status
- 4 - Beta
Framework
- AsyncIO
Intended Audience
- Developers
License
- OSI Approved :: MIT License
Operating System
- OS Independent
Programming Language
Topic
- Internet :: WWW/HTTP
Typing
- Typed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aioghost-0.4.19.tar.gz (96.7 kB view details)

Uploaded Jul 13, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

aioghost-0.4.19-py3-none-any.whl (8.1 kB view details)

Uploaded Jul 13, 2026 Python 3

File details

Details for the file aioghost-0.4.19.tar.gz.

File metadata

Download URL: aioghost-0.4.19.tar.gz
Upload date: Jul 13, 2026
Size: 96.7 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for aioghost-0.4.19.tar.gz
Algorithm	Hash digest
SHA256	`3b82cdcd921f764a3de5e37b33238f3b029c6a99f3b1fe69483537e9de53dc81`
MD5	`d5d1269e62f8a3f9bc0a7df16afc9fd0`
BLAKE2b-256	`1dc84e56dfb367f289c8a55df23c24f98d7452cdc23b3afc9d653fb3aeb5fe6b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for aioghost-0.4.19.tar.gz:

Publisher: publish.yml on TryGhost/aioghost

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: aioghost-0.4.19.tar.gz
- Subject digest: 3b82cdcd921f764a3de5e37b33238f3b029c6a99f3b1fe69483537e9de53dc81
- Sigstore transparency entry: 2162469467
- Sigstore integration time: Jul 13, 2026
Source repository:
- Permalink: TryGhost/aioghost@00ed637f9f8095e7dfc8a95d29d04feca46ea167
- Branch / Tag: refs/heads/main
- Owner: https://github.com/TryGhost
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@00ed637f9f8095e7dfc8a95d29d04feca46ea167
- Trigger Event: schedule