Breakreach for Python

The official Python SDK for the Breakreach API: schedule and publish social media posts to Instagram, TikTok, X, LinkedIn, YouTube, Facebook, Threads, Pinterest, Bluesky, Reddit, Telegram, Discord, Slack, Mastodon, WordPress, Ghost, Dev.to, Hashnode and Tumblr with one request shape.

• Typed from the OpenAPI spec (TypedDict responses), one method per endpoint
• Retries network errors, timeouts, 429s and restarts, with an Idempotency-Key on every POST so a retry never posts twice
• Standard library only, Python 3.9+

pip install breakreach

You need an API key: in Breakreach, open Settings → API & MCP and create one (br_...). API access comes with every plan, and the Developer plan bills per connected account.

Quickstart

from breakreach import Breakreach

br = Breakreach()  # reads BREAKREACH_API_KEY

accounts = br.list_accounts()["accounts"]

post = br.create_post(
    content="Meet Morning Light, our new blend. Out tomorrow.",
    account_ids=[a["id"] for a in accounts],
    media=["https://cdn.example.com/launch.jpg"],
    scheduled_at="2026-10-20T09:00:00",  # read in the workspace timezone
)["post"]

print(post["status"], post["scheduledAt"])  # scheduled, the UTC time

Arguments are snake_case; responses are the API's JSON as dicts, with its camelCase keys. Instead of scheduled_at, pass use_next_slot=True to take the next free slot of the workspace's posting schedule, publish_now=True to publish at once, or draft=True to save it for review in Breakreach.

Instagram, TikTok, YouTube and Pinterest need a photo or a video. Pinterest also needs pinterest_board_id (from list_pinterest_boards()), and TikTok takes tiktok_settings={"privacyLevel": "PUBLIC_TO_EVERYONE"}.

Local files

url = br.upload_media_file("launch.jpg")["url"]  # a path, bytes (with filename=) or an open file
br.create_post(content="…", account_ids=ids, media=[url], use_next_slot=True)

Up to 100 MB: JPG, PNG, WebP, GIF, MP4, MOV, WebM or PDF. A file that's already online goes through upload_media(url=...), which copies it to Breakreach storage so it's still there when the post goes out.

Several workspaces

northbeam = Breakreach(workspace="northbeam")  # every call goes there
br.list_accounts(workspace="acme")  # or say it per call

Leaving a field out vs sending null

PATCH calls change only the fields you pass. An argument you don't pass isn't sent; None is sent as null. So br.update_comment_dm_rule(rule_id, media_id=None) makes a rule watch every post, while leaving media_id out keeps its post.

Retries and idempotency

Every POST carries an Idempotency-Key. The SDK generates one per call and sends the same key on each retry, so when a response is lost after the post was created, the retry gets that post back instead of creating a second one. Pass your own to make re-runs of a whole job safe:

br.create_post(content=text, account_ids=ids, use_next_slot=True, idempotency_key=f"newsletter-{issue_id}")

Keys are kept 24 hours per API key. The same key with a different body is refused with a 422.

The client retries network errors, timeouts, 429s, and 5xx answers that come from the proxy rather than the API (a restart), twice by default with backoff, honouring Retry-After. Set max_retries and timeout (seconds) on the client, timeout per call.

Errors

from breakreach import BreakreachError, BreakreachConnectionError

try:
    br.create_post(content="Hi", account_ids=[], publish_now=True)
except BreakreachError as err:
    print(err.status, err.message)  # 400 accountIds is required…
except BreakreachConnectionError as err:
    print("no answer:", err)

message is the API's own reason, written to be shown to a person or an agent.

All methods

Also

• MCP server for Claude, ChatGPT, Cursor, Codex and other agents: https://api.breakreach.com/mcp
• TypeScript SDK and CLI: npm install breakreach, npx breakreach post …
• API reference and OpenAPI spec

MIT licensed.