SDKs

The official Node and Python clients, generated types, and what each resource covers.

SociaHive has two official clients for the REST API (/api/v1): @sociahive/sdk for Node and sociahive for Python. Both cover every scheduler endpoint, and their request and response types are generated from the same OpenAPI document the API serves at /api/v1/openapi.json, so they cannot drift from it.

A few scheduler features depend on your plan: AI images and client review and invite links are on Studio, Pro and Agency, and plugs on every paid plan. A call your plan does not include fails with status 403 and code feature_disabled.

Install

npm install @sociahive/sdk
pip install sociahive

This page describes version 0.2.0 of both packages. The Node package needs Node.js 18 or later.

Authenticate with an API key from Settings → API keys, or an OAuth token. Pass one, not both.

import { SociaHive } from '@sociahive/sdk'
const sh = new SociaHive({ apiKey: process.env.SOCIAHIVE_API_KEY! })

from sociahive import SociaHive
sh = SociaHive(api_key="sk_...")

Schedule into the next free slot

const { data: accounts } = await sh.accounts.list()
const ig = accounts.find((a) => a.platform === 'instagram')!
 
const slot = await sh.postingSlots.findSlot({ accountIds: [ig.id] })
const post = await sh.posts.create({
  text: 'New arrivals are in',
  platforms: [{ platform: ig.platform, account_id: ig.id }],
  schedule_type: 'scheduled',
  scheduled_at: slot.at,
  timezone: slot.timezone,
})

The slot is held for you for 10 minutes; create the post with scheduled_at set to at to keep it.

Resources

Node	Python	Endpoints
`accounts`	`accounts`	`GET /connected-accounts`
`posts`	`posts`	posts CRUD, `schedule`, `publish`, `cancel`, `bulk`, `duplicate`
`media`	`media`	`GET /media-library`, uploads (`presign`, `verify`, `uploadFromUrl`, one-call `upload`), AI images (`generateImage`, `imageAllowance`)
`signatures`	`signatures`	`/signatures` list, create, update, delete
`postingSlots`	`posting_slots`	`/posting-slots` CRUD, `occurrences`, `findSlot` (`GET /find-slot`)
`linkClicks`	`link_clicks`	`GET /posts/{id}/link-clicks`
`reviewLinks`	`review_links`	`/posts/{id}/review-links` list, create, revoke
`plugs`	`plugs`	`/posts/{id}/plugs` list, arm, delete
`calendar`	`calendar`	`GET /calendar`, `duplicate`, quick `stats`
`clientInvites`	`client_invites`	`/client-invites` list, create, revoke
`rssFeeds`	`rss_feeds`	`/rss-feeds` list, create, update, pause
`webhooks`	`webhooks`	`/webhooks` list, create, update, delete
`flows`, `analytics`	`flows`, `analytics`	automation flows and analytics

Review links and client invites return their URL once, when created. Store it; it is never returned again.

Arming a plug acts on a real audience when it fires (a repost or a comment), so confirm with the person before you call plugs.arm.

Types

Node exports every schema and operation of the spec under the Api namespace:

import type { Api } from '@sociahive/sdk'
 
type Slot = Api.FreeSlot
type CreateSlotBody = Api.BodyOf<'POST /posting-slots'>

Platform ids are typed KnownPlatform | (string & {}) in Node and str in Python, so a platform added after your SDK version still type-checks.

Python returns TypedDicts from sociahive.api.

Errors

Every non-2xx response raises SociaHiveError with status, code (for example no_slots, feature_disabled, allowance_exhausted) and the response body.

Verify webhook deliveries

import { verifyWebhookSignature } from '@sociahive/sdk'
 
const ok = await verifyWebhookSignature({
  body: rawBody,
  signature: req.headers['x-sociahive-signature'],
  secret: process.env.SOCIAHIVE_WEBHOOK_SECRET!,
})

from sociahive import verify_webhook_signature
 
ok = verify_webhook_signature(body=raw_body, signature=headers["X-SociaHive-Signature"], secret=secret)

See Webhooks for the events and payloads, and n8n for the no-code node.