TypeScript SDK method reference
Every public method of @socifyr/sdk 0.1.0, grouped by resource, with its signature and the REST call behind it. Each call unwraps { success, data } and returns data. Void methods resolve to undefined (an HTTP 204 returns undefined).
import { Socifyr } from '@socifyr/sdk'
const socifyr = new Socifyr({ apiKey: process.env.SOCIFYR_API_KEY!, workspaceId: process.env.SOCIFYR_WORKSPACE_ID! })Client
| Member | Signature | Calls |
|---|---|---|
| constructor | new Socifyr(config: SocifyrConfig) | none. Throws Error if apiKey or workspaceId is empty |
health | health(): Promise<HealthStatus> | GET /health |
HealthStatus is { status: 'ok' | 'degraded' | 'down', services: Record<string, 'ok' | 'down'> }.
How do I call the uploads methods?
Create methods
| Method | Signature | Calls |
|---|---|---|
video | video(params: UploadVideoParams): Promise<Upload> | POST /content/video |
photos | photos(params: UploadPhotosParams): Promise<Upload> | POST /content/photos |
text | text(params: UploadTextParams): Promise<Upload> | POST /content/text |
document | document(params: UploadDocumentParams): Promise<Upload> | POST /content/document |
bulkSchedule | bulkSchedule(params: BulkScheduleParams): Promise<BulkScheduleResult> | POST /content/bulk-schedule |
video, photos and document take medias entries as a Buffer, a Blob, a media library ID (24-char hex or starting with media_), or a public http(s) URL. A Buffer or Blob is first uploaded to POST /media/upload, and its ID is sent. A string that is neither an ID nor a URL is uploaded as file bytes, which is almost never what you want, so pass IDs or URLs as strings.
Shared fields (UploadOptions):
| Field | Type | Required | Notes |
|---|---|---|---|
connections | string[] | yes | Connection slugs, for example instagram-mybrand |
title | string | no | |
description | string | no | |
text | string | no | Caption or body. Required for text() (1 to 25000 chars per the type comment) |
scheduledAt | string | no | ISO-8601 |
timezone | string | no | IANA name, for example America/New_York |
firstComment | FirstComment | string | no | { text?, linkUrl?, imageUrl? } |
linkUrl | string | no | |
async | boolean | no | Return requestId only; poll for status |
saveDraft | boolean | no | Save a draft instead of publishing |
contentFormat | string | no | Hint such as short_video, story, photo_carousel |
platformOptions | Record<string, ConnectionOptions> | no | Keys: connection slug, ObjectId or platform name |
bulkSchedule takes { rows?: BulkScheduleRow[], csv?: string }. Provide one. Row: { text: string, connections: string[] | string, scheduledAt: string, title?: string }. CSV header: text,connections,scheduledAt,title. Returns { created: number, failed: { row: number, error: string }[] }. One bad row does not abort the batch.
The ack returned by create, publishNow, retry, publishDraft, update, archive and unarchive is an Upload:
interface Upload {
id?: string // normalized from uploadId or draftId
requestId?: string
usage?: { count: number; limit: number; remaining: number } // -1 = unlimited
message?: string
scheduledAt?: string
totalChannels?: number
retriedChannels?: number // retry only
}Example response of an immediate text post:
{ "id": "6b1f0c2a9d3e4f5a6b7c8d9e", "requestId": "9f2c7a1e-3d44-4b2a-8e1f-0a5c2d7e9f10", "usage": { "count": 4, "limit": 100, "remaining": 96 } }With async: true there is no id, only requestId, message and totalChannels.
Status, list and lifecycle
| Method | Signature | Calls |
|---|---|---|
getStatus | getStatus(requestId: string): Promise<UploadStatusResponse> | GET /content/status?requestId= (accepts a content ID too) |
waitForCompletion | waitForCompletion(requestId: string, intervalMs = 3000, timeoutMs = 300000): Promise<UploadStatusResponse> | polls getStatus until completed, failed or partial_failure; throws plain Error on timeout |
list | list(query?: UploadHistoryQuery): Promise<UploadListResponse> | GET /content |
get | get(id: string): Promise<UploadDetail> | GET /content/:id |
update | update(id: string, params: UpdateDraftParams): Promise<Upload> | PATCH /content/:id |
cancel | cancel(id: string): Promise<void> | DELETE /content/:id |
publishNow | publishNow(id: string): Promise<Upload> | POST /content/:id/publish-now |
publishDraft | publishDraft(id: string): Promise<Upload> | POST /content/:id/publish |
retry | retry(id: string): Promise<Upload> | POST /content/:id/retry |
archive | archive(id: string): Promise<Upload> | PATCH /content/:id/archive |
unarchive | unarchive(id: string): Promise<Upload> | PATCH /content/:id/unarchive |
bulkDelete | bulkDelete(ids: string[]): Promise<void> | POST /content/bulk-delete |
bulkArchive | bulkArchive(ids: string[]): Promise<void> | POST /content/bulk-archive |
bulkUnarchive | bulkUnarchive(ids: string[]): Promise<void> | POST /content/bulk-unarchive |
UploadHistoryQuery: page?, limit?, status?, platform?, type?, from?, to?. list returns { data: UploadSummary[], meta: { total, page, limit, totalPages } }.
UploadStatus values in the type: draft, pending, queued, processing, publishing, completed, partial_failure, failed. The API can also return pending_approval (a key with requireApproval creates posts in that state; the create ack then carries uploadId, status: 'pending_approval' and a message). The type does not list it.
UpdateDraftParams: type?, connections?, title?, description?, text?, firstComment?, mediaIds?, scheduledAt?, timezone?, platformOptions?, contentFormat?. Note it uses mediaIds, not medias.
Status example:
const status = await socifyr.uploads.getStatus(ack.requestId!)
// { requestId, uploadId, status: 'partial_failure', type: 'video', channels: [
// { platform: 'youtube', connectionId, targetName, result: { status: 'success', postId, postUrl, publishedAt } },
// { platform: 'instagram', connectionId, result: { status: 'failed', error: '...' } } ], createdAt }See Uploads for runnable end-to-end examples.
How do I call the media methods?
| Method | Signature | Calls |
|---|---|---|
upload | upload(file: Buffer | Blob, filename?: string): Promise<MediaItem> | POST /media/upload (multipart) |
list | list(query?: MediaQuery): Promise<PaginatedResponse<MediaItem>> | GET /media |
get | get(id: string): Promise<MediaItem> | GET /media/:id |
update | update(id: string, metadata: MediaMetadata): Promise<MediaItem> | POST /media/:id |
delete | delete(id: string): Promise<void> | DELETE /media/:id |
bulkDelete | bulkDelete(ids: string[]): Promise<void> | POST /media/bulk-delete |
MediaQuery: type? (image, video, document), search?, page?, limit?, sortBy? (createdAt, name), sortOrder? (asc, desc). MediaMetadata: alt?, description?, tags?. PaginatedResponse is typed as { results, total, page, limit, pages }. See Media.
How do I call the AI methods?
| Method | Signature | Calls |
|---|---|---|
status | status(): Promise<AiStatus> | GET /ai/status |
generateContent | generateContent(params: GenerateContentParams): Promise<GeneratedContent> | POST /ai/generate-content |
suggestHashtags | suggestHashtags(params: SuggestHashtagsParams): Promise<SuggestedHashtags[]> | POST /ai/suggest-hashtags |
See AI.
How do I call the analytics methods?
| Method | Signature | Calls |
|---|---|---|
get | get(query?: AnalyticsQuery): Promise<Analytics> | GET /analytics |
sync | sync(): Promise<AnalyticsSyncResult> | POST /analytics/sync |
followers | followers(query?: AccountAnalyticsQuery): Promise<FollowerGrowth> | GET /analytics/followers |
accounts | accounts(query?: AccountAnalyticsQuery): Promise<AccountComparison> | GET /analytics/accounts |
getPost | getPost(uploadId: string): Promise<PostAnalytics> | GET /analytics/post/:uploadId |
getPlatformMetrics | getPlatformMetrics(): Promise<PlatformMetric[]> | GET /analytics/platform-metrics |
AnalyticsQuery: from?, to?, platform?, granularity? (daily, weekly, monthly). AccountAnalyticsQuery: period? (last_day, last_week, last_month, last_3months, last_year), from?, to?, connection? (slug), platform?. See Analytics.
How do I call the engagement methods?
| Method | Signature | Calls |
|---|---|---|
backfill | backfill(): Promise<{ enqueued: number }> | POST /engagement/backfill |
resetInsights | resetInsights(platform?: string): Promise<{ cleared: number; enqueued: number }> | POST /engagement/reset-insights?platform= |
See Engagement.
How do I call the webhook methods?
| Method | Signature | Calls |
|---|---|---|
create | create(params: CreateWebhookParams): Promise<Webhook> | POST /webhooks |
list | list(): Promise<Webhook[]> | GET /webhooks |
get | get(id: string): Promise<Webhook> | GET /webhooks/:id |
update | update(id: string, params: UpdateWebhookParams): Promise<Webhook> | PATCH /webhooks/:id |
delete | delete(id: string): Promise<void> | DELETE /webhooks/:id |
deliveries | deliveries(webhookId: string): Promise<WebhookDelivery[]> | GET /webhooks/:id/deliveries |
Top-level helpers: verifyWebhookSignature(payload: string | Buffer, signature: string | undefined | null, secret: string): boolean and parseWebhookEvent(payload: string | Buffer): WebhookEventPayload. Constants: WEBHOOK_EVENTS, PLATFORMS. See Webhooks.
How do I call the workspaces methods?
All workspaceId parameters are explicit. The client's own workspaceId is only sent as the X-Workspace-Id header.
| Method | Signature | Calls |
|---|---|---|
usage | usage(): Promise<UsageSummary> | GET /usage |
create | create(params: { name: string }): Promise<Workspace> | POST /workspaces |
list | list(): Promise<Workspace[]> | GET /workspaces |
get | get(id: string): Promise<Workspace> | GET /workspaces/:id |
update | update(id: string, params: { name: string }): Promise<Workspace> | PATCH /workspaces/:id |
delete | delete(id: string): Promise<void> | DELETE /workspaces/:id |
listConnections | listConnections(workspaceId: string): Promise<Connection[]> | GET /workspaces/:id/connections |
refreshConnection | refreshConnection(workspaceId: string, connection: string): Promise<ConnectionRefreshResult> | POST /workspaces/:id/connections/:connection/refresh |
getReconnectLink | getReconnectLink(connection: string): Promise<ReconnectLink> | POST /oauth/connections/:connection/reconnect-link |
forkConnection | forkConnection(workspaceId, connectionId, { targetId, targetName, targetImageUrl? }): Promise<Record<string, unknown>> | POST /workspaces/:id/connections/:connectionId/fork |
updateConnectionTarget | updateConnectionTarget(workspaceId, connectionId, { targetId, targetName }): Promise<void> | PATCH /workspaces/:id/connections/:connectionId/target |
deleteConnection | deleteConnection(workspaceId, connectionId): Promise<void> | DELETE /workspaces/:id/connections/:connectionId |
revokeConnection | revokeConnection(workspaceId, connectionId): Promise<void> | DELETE /workspaces/:id/connections/:connectionId/revoke |
disconnectPlatform | disconnectPlatform(workspaceId, platform: Platform): Promise<void> | DELETE /workspaces/:id/platforms/:platform |
revokePlatform | revokePlatform(workspaceId, platform: Platform): Promise<void> | DELETE /workspaces/:id/platforms/:platform/revoke |
updatePlatformTarget | updatePlatformTarget(workspaceId, platform, { targetId, targetName }): Promise<void> | PATCH /workspaces/:id/platforms/:platform/target |
listMembers | listMembers(workspaceId): Promise<WorkspaceMember[]> | GET /workspaces/:id/members |
updateMemberRole | updateMemberRole(workspaceId, userId, roleKey: InvitableRole): Promise<void> | PATCH /workspaces/:id/members/:userId/role |
removeMember | removeMember(workspaceId, userId): Promise<void> | DELETE /workspaces/:id/members/:userId |
invite | invite(workspaceId, { email, roleKey: InvitableRole }): Promise<Invitation> | POST /workspaces/:id/invitations |
listInvitations | listInvitations(workspaceId): Promise<Invitation[]> | GET /workspaces/:id/invitations |
cancelInvitation | cancelInvitation(workspaceId, invitationId): Promise<void> | DELETE /workspaces/:id/invitations/:invitationId |
listApiKeys | listApiKeys(workspaceId): Promise<ApiKey[]> | GET /workspaces/:id/api-keys |
createApiKey | createApiKey(workspaceId, { label }): Promise<ApiKeyWithSecret> | POST /workspaces/:id/api-keys |
updateApiKey | updateApiKey(workspaceId, keyId, params: UpdateApiKeyParams): Promise<{ success: boolean; id: string }> | PUT /workspaces/:id/api-keys/:keyId |
deleteApiKey | deleteApiKey(workspaceId, keyId): Promise<void> | DELETE /workspaces/:id/api-keys/:keyId |
Roles: WorkspaceRole is OWNER | ADMIN | EDITOR | CONTRIBUTOR. InvitableRole excludes OWNER.
UpdateApiKeyParams: label?, dailyPostLimit?: number | null, monthlyXSpendCentsCap?: number | null (US cents), requireApproval?: boolean. Pass null to remove a cap.
UsageSummary:
{
tier: 'free' | 'pro' | 'business'
uploads: UsageDimension // { used, limit: number | null, remaining: number | null, unlimited: boolean }
accounts: UsageDimension
xPosts: UsageDimension
xSpendUsd: number
storage: UsageDimension & { usedBytes: number; limitBytes: number | null }
}See Workspaces and Connections.
FAQ
Do the types match the API exactly?
They are hand-written to match the API. Two known quirks: PaginatedResponse (used by media.list) is typed with results and pages, while uploads.list returns data and meta.totalPages. Check the actual response if a field looks missing.
Which error does each method throw?
All of them throw the classes in Errors.