Developer Quickstart

Five-minute path from zero to a working SociaHive integration via REST, SDKs, or the CLI.

Hit the REST API directly, install the official SDK in your language, or script with the CLI. Five minutes to first "oh-that-actually-works".

Get an API key

Settings → API Keys → Generate. Minimum useful scope set:

accounts:read  posts:read  posts:write  flows:read  flows:write

Copy the key — it starts with sk_ and is shown only once. Set it in your shell:

export SOCIAHIVE_API_KEY=sk_...

Hit your first endpoint

curl -H "X-API-Key: $SOCIAHIVE_API_KEY" \
  https://www.sociahive.com/api/v1/connected-accounts

You should get back JSON listing your connected social media accounts. Save one of the id values — you'll need it to create posts.

Browse the reference

Surface	URL
OpenAPI 3.1 spec (machine-readable)	/api/v1/openapi.json
Scalar UI (human-readable, try-it-now)	/api/v1/docs

Drop the spec URL into Postman, ChatGPT Custom GPT Actions, or any OpenAPI-driven SDK generator.

Install an SDK

npm install @sociahive/sdk

import { SociaHive } from '@sociahive/sdk'
 
const sh = new SociaHive({ apiKey: process.env.SOCIAHIVE_API_KEY! })
 
const { data: accounts } = await sh.accounts.list()
console.log(`Connected to ${accounts.length} accounts`)
 
const post = await sh.posts.create({
  text: 'Hello from the SDK',
  platforms: [{ platform: 'instagram', account_id: accounts[0].id }],
  schedule_type: 'scheduled',
  scheduled_at: '2026-06-01T09:00:00Z',
  timezone: 'UTC',
})
console.log(`Scheduled post ${post.id}`)

Both SDKs ship typed clients with the same resource grouping (accounts, posts, flows, analytics), ergonomic error classes (SociaHiveError with isAuthError, isRateLimited, etc.), and auto-unwrapping of v1 response envelopes.

Use the CLI for ad-hoc operations

The sociahive CLI wraps the REST API for shell-friendly use:

npm install -g sociahive
export SOCIAHIVE_API_KEY=sk_...
 
sociahive accounts list
sociahive posts list --status scheduled --limit 20
sociahive posts create \
  --text "Hello!" \
  --platforms '[{"platform":"instagram","account_id":"..."}]' \
  --schedule-type immediate
sociahive flows generate \
  --description "Auto-reply to comments containing price" \
  --account-id <account_id> \
  --platform-user-id <platform_user_id>

Pipe-friendly JSON output by default. Useful inside CI/CD, cron jobs, and quick "what's the state of X" checks.

Generate types from OpenAPI (optional)

Our SDKs cover the high-traffic endpoints with hand-curated types. For endpoints beyond that surface, generate types directly from the spec:

npx openapi-typescript https://www.sociahive.com/api/v1/openapi.json \
  -o sociahive.d.ts

You'll get fully typed request/response shapes for every endpoint in the spec; combine with fetch or axios for surfaces the SDK doesn't yet wrap.

Authentication options

API key auth (above) is the fastest path. For multi-user applications where each end-user should authorize SociaHive access themselves, use OAuth 2.1 with Dynamic Client Registration:

Surface	URL
Authorization endpoint	`https://www.sociahive.com/api/oauth/authorize`
Token endpoint	`https://www.sociahive.com/api/oauth/token`
Dynamic registration	`https://www.sociahive.com/api/oauth/register`
Discovery	`https://www.sociahive.com/.well-known/oauth-authorization-server`

Both SDKs accept oauthToken as an alternative to apiKey:

const sh = new SociaHive({ oauthToken: 'mcp_at_...' })

Error handling

Every non-2xx response throws a SociaHiveError (Node) / SociaHiveError (Python) carrying status, code, and the response body:

import { SociaHive, SociaHiveError } from '@sociahive/sdk'
 
try {
  await sh.posts.create({ /* ... */ })
} catch (err) {
  if (err instanceof SociaHiveError) {
    if (err.isAuthError) console.error('Bad API key or insufficient scope')
    else if (err.isRateLimited) console.error('Rate limit — slow down')
    else console.error(`HTTP ${err.status}: ${err.message}`)
  } else throw err
}