SDKs

Official client libraries wrap the /v1 API and handle auth, errors, and webhook signature verification.

Python

pip install herald-sdk        # or: uv add herald-sdk

import asyncio
from herald import HeraldClient

async def main():
    async with HeraldClient(api_key="hld_…") as h:
        accounts = (await h.list_accounts())["accounts"]
        post = await h.create_post(targets=[accounts[0]["id"]], text="Launch day! ✨", mode="now")
        print(post["status"], post["targets"][0].get("permalink"))

asyncio.run(main())

Errors raise HeraldError (.status, .code, .message). Verify webhooks with verify_webhook(secret, raw_body, signature_header).

TypeScript

npm install @herald/sdk

import { HeraldClient } from "@herald/sdk";

const herald = new HeraldClient({ apiKey: process.env.HERALD_API_KEY! });
const { accounts } = await herald.listAccounts();
const post = await herald.createPost({ targets: [accounts![0].id], text: "Launch day! ✨", mode: "now" });
console.log(post.status, post.targets[0]?.permalink);

Non-2xx throws HeraldError. Verify webhooks with verifyWebhook(secret, rawBody, signatureHeader).

Methods

Both clients cover the full surface: me, usage, list_accounts / get_account / get_account_stats / connect / connect_wordpress / connect_bluesky / connect_mastodon / disconnect_account / delete_account, upload_media, create_post / list_posts / get_post / get_post_stats / edit_post / publish_post / cancel_post / retry_post / delete_post / unpublish_post, and create_webhook / list_webhooks / delete_webhook.