Skip to main content

SociaHive

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

PyPI: sociahive Python versions License: MIT

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

Instagram   Facebook   LinkedIn   X   Threads   TikTok   YouTube   Bluesky   Pinterest

Also Telegram channels, Discord, Slack, Mastodon, Lemmy, Tumblr, Dev.to, Hashnode, WordPress, Listmonk, Dribbble, Twitch and Kick.

Automate DMs and comments on

Instagram   Facebook   Messenger   WhatsApp   Telegram

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.

ChatGPT   Claude   Claude Code   Cursor   Codex   Gemini   Grok   MCP

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.

License

MIT

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)

Source distribution for sociahive 0.2.0
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)

Table of built distributions (wheels) for sociahive 0.2.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page