socioi.comDocs

Node SDK

TypeScript/Node client for the Socioi Public API — same idea as Postiz @postiz/node.

@socioi/sdk is a thin typed client for the Public API. Use it from Node, Next.js server actions, scripts, and backends — no raw fetch boilerplate.

Use…When…
Public APIAny language / curl
Node SDK (this page)TypeScript or Node apps
AI Agents CLIShell agents (Claude Code, OpenClaw)
MCPClaude, ChatGPT, Cursor
n8nVisual workflows

Same si_live_… API key (or pos_… OAuth token) as the Public API.

Install

The package lives in the Socioi monorepo as @socioi/sdk. It is not on the public npm registry yet:

Bash
pnpm install
pnpm --filter @socioi/sdk build

When published:

Bash
npm install @socioi/sdk

Quick start

TypeScript
import Socioi from '@socioi/sdk';

const socioi = new Socioi('si_live_YOUR_KEY');
// optional API origin (local): new Socioi('si_live_…', 'http://localhost:4000')

const channels = await socioi.channels(); // alias: integrations()

await socioi.post({
  type: 'schedule',
  date: '2026-09-20T10:00:00.000Z',
  content: 'Hello from the Socioi SDK',
  channelIds: [channels[0].id],
});

Create a key in Settings → Developers → Access.

Methods

MethodMaps to
isConnected()GET /is-connected
channels() / integrations()GET /channels
quota()GET /channels/quota
post(body) / createPost(body)POST /posts
postList(filters) / listPosts(filters)GET /posts
getPost(id)GET /posts/:id
schedulePost(id, scheduledAt)POST /posts/:id/schedule
changePostStatus(id, status)PATCH /posts/:id/status
deletePost(id)DELETE /posts/:id
listMedia()GET /media
upload(buffer, fileName)Signed upload (upload-url → PUT → confirm)
uploadFromUrl(url)POST /media/upload-from-url
deleteMedia(id)DELETE /media/:id
tiktokCreatorInfo(channelId)GET /channels/:id/tiktok/creator-info
tiktokAnalytics(channelId, { days?, cursor? })GET /channels/:id/tiktok/analytics

integrations, post, postList, upload, and deletePost mirror Postiz’s @postiz/node names for an easier migration.

Typed provider settings

YouTubeSettings and TikTokSettings type the settings object on each posts[] item. Collect these values from the user rather than inventing them. Field rules: Provider settings.

TypeScript
import Socioi, { type TikTokSettings, type YouTubeSettings } from '@socioi/sdk';

const youtube: YouTubeSettings = {
  __type: 'youtube',
  title: 'How we plan a week of social',
  description: 'Our weekly planning routine.',
  privacyStatus: 'unlisted',
  madeForKids: false,
};

// TikTok direct post: read allowed options first and let the user choose.
const info = await socioi.tiktokCreatorInfo('TIKTOK_CHANNEL_ID');
const tiktok: TikTokSettings = { __type: 'tiktok', postMode: 'direct', privacyLevel: 'SELF_ONLY' };

await socioi.post({
  type: 'now',
  posts: [
    { channelId: 'YOUTUBE_CHANNEL_ID', content: 'New video', mediaIds: ['VIDEO_ID'], settings: youtube },
    ...(info.canPost
      ? [{ channelId: 'TIKTOK_CHANNEL_ID', content: 'New video', mediaIds: ['VIDEO_ID'], settings: tiktok }]
      : []),
  ],
});

Upload example

TypeScript
import { readFileSync } from 'fs';

const media = await socioi.upload(readFileSync('./photo.jpg'), 'photo.jpg');
// or remote:
// const media = await socioi.uploadFromUrl('https://example.com/photo.jpg');

await socioi.post({
  type: 'now',
  content: 'Photo post',
  channelIds: ['CHANNEL_ID'],
  mediaIds: [media.id],
});

Errors

Failed calls throw SocioiError with status, details, and optional retryAfter when rate-limited (429). See Errors & rate limits.