Social media API SDK

Social media API SDK for TypeScript and Python

Socifyr ships two official SDKs for its social media posting API: @socifyr/sdk for TypeScript and Node, and socifyr for Python. Both take an API key and a workspace ID, then publish to 18 platforms by connection slug. Retries, typed responses, status polling, webhook signature checks and token renewal are built in, so you write the post and the SDK handles the plumbing.
Start freeSDK docs
2
SDKs: TypeScript and Python
18
platforms, one key
3
connected accounts on Free
30
free uploads per month

What you get

  • Typed TypeScript client

    uploads, media, ai, analytics, webhooks and workspaces resources with typed params and a normalized Upload ack.

  • Python with the same shape

    client.uploads.text(...), bulk_schedule, analytics and AI helpers, with a SocifyrError hierarchy.

  • Retries and timeouts

    The TypeScript client defaults to a 30 second timeout and 2 retries. Both are configurable.

  • Webhook verification

    verifyWebhookSignature and parseWebhookEvent are exported so your handler can reject forged events.

How do I install the Socifyr SDK?

bash
# TypeScript / Node
npm install @socifyr/sdk

# Python
pip install socifyr

How do I publish a post with the TypeScript SDK?

typescript
import { Socifyr } from '@socifyr/sdk'

const socifyr = new Socifyr({
  apiKey: process.env.SOCIFYR_API_KEY!,
  workspaceId: process.env.SOCIFYR_WORKSPACE_ID!,
})

// Text to several accounts, by slug
const upload = await socifyr.uploads.text({
  connections: ['x-myhandle', 'linkedin-mybrand', 'bluesky-mybrand'],
  text: 'Just shipped our new SDK!',
})

// Wait for the per-platform result (accepts the id or the requestId)
const result = await socifyr.uploads.waitForCompletion(upload.id!)
console.log(result.status) // 'completed' | 'partial_failure' | 'failed'

// Schedule: pass scheduledAt on any create call (paid plans)
await socifyr.uploads.text({
  connections: ['linkedin-mybrand'],
  text: 'Goes live tomorrow at 9',
  scheduledAt: '2026-12-01T09:00:00Z',
})
Video with per-account options
typescript
import fs from 'node:fs'

await socifyr.uploads.video({
  connections: ['instagram-mybrand', 'tiktok-mybrand'],
  medias: [fs.readFileSync('./video.mp4')],
  title: 'Check this out!',
  platformOptions: {
    'instagram-mybrand': { mediaType: 'REELS' },
    'tiktok-mybrand': { privacyLevel: 'PUBLIC_TO_EVERYONE' },
  },
})

medias accepts raw buffers, media library IDs or public URLs. Text posts allow up to 25,000 characters before per-platform limits apply; see caption length limits per platform.

How do I publish with the Python SDK?

python
from socifyr import Socifyr

client = Socifyr(api_key="sk_...", workspace_id="ws_...")
# or set SOCIFYR_API_KEY / SOCIFYR_WORKSPACE_ID in the environment

client.uploads.text(
    connections=["instagram-mybrand", "x-myhandle"],
    text="Shipped a new feature",
)

# Schedule for later
client.uploads.text(
    connections=["linkedin-mybrand"],
    text="Scheduled post",
    scheduled_at="2026-06-01T09:00:00Z",
)

# Bulk schedule, or pass csv="text,connections,scheduledAt,title\n..."
res = client.uploads.bulk_schedule(rows=[
    {"text": "Morning", "connections": ["x-me"], "scheduledAt": "2026-06-01T09:00:00Z"},
    {"text": "Evening", "connections": ["x-me"], "scheduledAt": "2026-06-01T18:00:00Z"},
])
print(f"{res['created']} scheduled, {len(res['failed'])} failed")

The Python client also exposes client.workspaces.list_connections(...), client.usage(), client.analytics.get/followers/accounts(...) and client.ai.generate_caption(...). Failures raise a SocifyrError subclass: AuthenticationError, RateLimitError, UsageLimitError, NotFoundError or ValidationError.

How do I renew an expired account from code?

try {
  const r = await socifyr.workspaces.refreshConnection(workspaceId, 'instagram-mybrand')
  console.log(r.status, r.expiresAt)
} catch {
  // The platform cannot refresh. Get a one-time link for the owner.
  const link = await socifyr.workspaces.getReconnectLink('instagram-mybrand')
  console.log(link.url, link.expiresIn) // seconds until expiry
}

The reconnect link is single-use, valid for 10 minutes, and contains no access token. Only the workspace owner can approve it.

What does the TypeScript SDK cover?

Resource groups on the TypeScript client
ResourceMethods
socifyr.uploadsvideo, photos, text, document, bulkSchedule, getStatus, waitForCompletion, list, get, update, cancel, publishNow, publishDraft, retry, archive, bulkDelete
socifyr.mediaupload, list, get, update, delete, bulkDelete
socifyr.analyticsget, sync, getPost, getPlatformMetrics, followers, accounts
socifyr.aistatus, generateContent, suggestHashtags
socifyr.webhookscreate, list, get, update, delete, deliveries
socifyr.workspacesconnections (listConnections, refreshConnection, getReconnectLink), members, invitations and API keys

Frequently asked questions

Which languages have an official Socifyr SDK?

TypeScript and Node (@socifyr/sdk) and Python (socifyr). Any other language can call the REST API directly.

How does the SDK handle failures?

It retries transient network errors (2 retries by default in TypeScript) and throws typed errors such as AuthenticationError, RateLimitError, UsageLimitError and ValidationError. A post to several accounts can partially fail, so check the result of waitForCompletion and call retry for failed channels.

Can I get notified instead of polling?

Yes. Webhooks deliver events when a post finishes or a platform fails. Verify each request with verifyWebhookSignature. Webhook endpoints are included on the Business plan.

Do I need the platform OAuth tokens in my code?

No. You pass an API key and a workspace ID, and target accounts by slug.

Is there an async mode for large uploads?

Yes. Pass async: true and the call returns a requestId immediately. Poll getStatus with it.

Related

Put social media api sdk to work

One key, 18 platforms, flat pricing from $9.99. The free plan needs no card.

Start freeSDK docs