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
aiohttpfor 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.
1 maintainer
Metadata
1 maintainer
Release files for aioghost 0.4.28
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| aioghost-0.4.28.tar.gz | 110.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| aioghost-0.4.28-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 118.7 kB
Release files / aioghost-0.4.28.tar.gz
| Download URL | aioghost-0.4.28.tar.gz |
|---|---|
| Size | 110.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5e9a7ef76e79f4090dd23419961e310180900e71d10059d36ee0e4ade22c234d
|
|
BLAKE2b-256 checksum How to use checksums |
bb39f458d00fc0b52eca90c898ffd3635c0b1e1cfc0cd74af447db49f8792e94
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency logRelease files / aioghost-0.4.28-py3-none-any.whl
| Download URL | aioghost-0.4.28-py3-none-any.whl |
|---|---|
| Size | 8.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c417163504dae6797e9064b9d615de49e3cbf8cc4d0f7374432722bb775437a0
|
|
BLAKE2b-256 checksum How to use checksums |
e331f452773c87f5451aa45bbd5fdd3a9d97d3346cfdb94eb95e88adcd138486
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency log
