Run your social media from your AI tool: schedule posts, build DM and comment automations, and read analytics.
This is the official Python SDK for the SociaHive API.
Website · Developers · Docs · Connect your AI · Sign up
sociahive
Official Python SDK for the SociaHive API: schedule and publish posts, manage your media library, posting slots, signatures, client review links and plugs, build and run DM and comment automations, receive webhooks and read analytics from your own code.
API access is part of the 7-day trial and every paid plan. On the free plan the API answers 403 upgrade_required.
pip install sociahive
Quickstart
from sociahive import SociaHive
sh = SociaHive(api_key="sk_...")
accounts = sh.accounts.list()
print(f"Connected: {[a['platform'] for a in accounts['data']]}")
post = sh.posts.create(
text="Hello from Python!",
platforms=[{"platform": "instagram", "account_id": accounts["data"][0]["id"]}],
schedule_type="scheduled",
scheduled_at="2027-03-01T09:00:00Z", # any future time
timezone="UTC",
)
print(f"Scheduled post {post['id']}")
Auth
Pass exactly one of api_key (long-lived) or oauth_token (per-user OAuth):
sh = SociaHive(api_key="sk_...")
sh = SociaHive(oauth_token="mcp_at_...")
Generate keys at https://www.sociahive.com/settings?tab=api-keys.
Context manager
The client holds an httpx.Client connection pool. Use with for tight scopes:
with SociaHive(api_key="sk_...") as sh:
account = sh.accounts.list()["data"][0]
# flows.list needs the account's platform_user_id
for flow in sh.flows.list(platform_user_id=account["platform_user_id"])["data"]:
print(flow["name"], flow["status"])
Outside a with block, call sh.close() when you're done.
Error handling
from sociahive import SociaHive, SociaHiveError
try:
sh.posts.create(text="...", platforms=[...])
except SociaHiveError as err:
if err.is_auth_error:
print("Bad API key or insufficient scope")
elif err.is_rate_limited:
print(f"Rate limited, retry in {err.retry_after}s")
else:
print(f"HTTP {err.status}: {err}")
Rate limits
Limits are per user, across all your keys: 120 reads and 30 writes a minute, 5 a minute for AI generation, and 1,000 requests a day in total. A 429 carries a Retry-After header (err.retry_after); wait that long before retrying. See rate limits.
Bulk actions on posts
sh.posts.bulk applies one action to up to 50 existing posts. It does not create posts; call sh.posts.create for each one.
sh.posts.bulk("schedule", ["p1", "p2"], scheduled_for="2027-03-01T09:00:00Z")
sh.posts.bulk("update_status", ["p3"], status="draft")
sh.posts.bulk("delete", ["p4"])
What's covered
| Resource | Methods |
|---|---|
sh.accounts |
list |
sh.posts |
list, get, create, update, delete, schedule, publish, cancel, bulk, duplicate |
sh.media |
list (media library), upload (presign, PUT and verify in one call), presign, verify, upload_from_url, generate_image, image_allowance |
sh.signatures |
list, create, update, delete |
sh.posting_slots |
list, create, update, delete, occurrences, find_slot |
sh.link_clicks |
get |
sh.review_links |
list, create, revoke |
sh.plugs |
list, arm, delete |
sh.calendar |
month, duplicate, stats |
sh.client_invites |
list, create, revoke |
sh.rss_feeds |
list, create, update, pause |
sh.webhooks |
list, create, update, delete |
sh.flows |
list, get, create, update, delete, activate, deactivate, add_node, update_node, add_edge, stats, collected_data, generate |
sh.analytics |
get, export, content_insights |
Some features depend on your plan: client review links, client invites and AI images need Studio or above, plugs need Creator or above. On a plan without the feature its calls raise SociaHiveError with status == 403.
Schedule into the next free posting slot:
slot = sh.posting_slots.find_slot(account_ids=[account_id])
sh.posts.create(
text="New arrivals are in",
platforms=[{"platform": "instagram", "account_id": account_id}],
schedule_type="scheduled",
scheduled_at=slot["at"],
timezone=slot["timezone"],
)
Types
Return values are TypedDicts generated from SociaHive's OpenAPI document, in
sociahive.api (for example api.FreeSlot, api.MediaLibraryPage). Platform
ids are plain str, so a platform added later needs no SDK release.
Webhooks
sh.webhooks.create(target_url=..., events=[...]) subscribes an HTTPS endpoint.
verify_webhook_signature checks the X-SociaHive-Signature header of a
delivery (HMAC-SHA256 with a five-minute replay window):
from sociahive import verify_webhook_signature
ok = verify_webhook_signature(body=raw_body, signature=headers["X-SociaHive-Signature"], secret=secret)
Platforms
Publish to
Also Telegram channels, Discord, Slack, Mastodon, Lemmy, Tumblr, Dev.to, Hashnode, WordPress, Listmonk, Dribbble, Twitch and Kick.
Automate DMs and comments on
Development
pip install -e ".[dev]"
pytest
For other endpoints, fall back to httpx directly with X-API-Key. Full spec:
https://www.sociahive.com/api/v1/openapi.json.
Works with your AI tool
Prefer to ask instead of writing code? The same account works from your AI tool through the SociaHive MCP server.
Data and permissions
- An API key only reaches what its scopes allow (for example
posts:read,posts:write,flows:write). Revoke a key any time in Settings > API keys. - Accounts connect through each platform's official login and APIs. SociaHive does not scrape and never asks for your account password (Bluesky uses an app password, Telegram a bot token).
- Platform tokens are stored encrypted on SociaHive's servers and are never returned by the API.
Links
- Developer quickstart · API reference (OpenAPI)
- Node.js SDK · Cookbook · MCP server and plugins
- Changelog
License
Metadata
Release files for sociahive 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sociahive-0.2.0.tar.gz | 21.3 kB | Without provenance | Details for sociahive-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sociahive-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for sociahive-0.2.0-py3-none-any.whl |
Total release size: 40.9 kB
Release files / sociahive-0.2.0.tar.gz
| Download URL | sociahive-0.2.0.tar.gz |
|---|---|
| Size | 21.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
abf42311c1a719d460eb8d3fc79aa92c1e127fa8eb2e22f7d07c0a35c1236896
|
|
BLAKE2b-256 checksum How to use checksums |
1715ef17f192268158ec46761d8fb8a58d586fe350965ee4688156f29c279936
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Release files / sociahive-0.2.0-py3-none-any.whl
| Download URL | sociahive-0.2.0-py3-none-any.whl |
|---|---|
| Size | 19.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ed52b9acf445c19e501f9662cb8c1d812d5abf77bbfabdad3e33810d96f80504
|
|
BLAKE2b-256 checksum How to use checksums |
a617ca931f378c56b75e800cbb42c4317f0a34d2e2a7c84203cfc5967d374617
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Security for sociahive 0.2.0
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.