Social media

Social media endpoints of the Zanfia Workspace API, with schemas and code samples.

8 min readLast updated Oct 23, 2026

Connected social accounts and posts: drafts land in the dashboard Posts view, scheduling publishes at a set time, immediate publish is LinkedIn-only. Threads, YouTube and TikTok are in early access: only workspaces with early access can connect them. Requires the social:read / social:write scopes. All routes require a Authorization: Bearer header — see Authentication.

GET/social/accounts

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Response Body

`application/json`

`application/json`

curl -X GET "https://example.com/social/accounts"

{  "count": 0,  "accounts": [    {      "target": "string",      "network": "linkedin",      "label": "string",      "displayName": "string",      "handle": "string",      "profileUrl": "string",      "supportsScheduling": true,      "supportsImmediatePublish": true    }  ]}

{  "error": "string",  "message": "string"}

GET/social/posts

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Response Body

`application/json`

`application/json`

curl -X GET "https://example.com/social/posts"

{  "count": 0,  "posts": [    {      "id": "string",      "status": "draft",      "text": "string",      "targets": [        "string"      ],      "media": [        {          "mediaId": "string",          "url": "string",          "type": "image",          "name": "string"        }      ],      "firstComment": "string",      "youtube": {        "tags": [          "string"        ],        "categoryId": "string",        "notifySubscribers": true,        "embeddable": true,        "publicStatsViewable": true,        "license": "youtube",        "containsSyntheticMedia": true,        "defaultLanguage": "string",        "defaultAudioLanguage": "string",        "recordingDate": "string",        "thumbnailMediaId": "string",        "playlistId": "string",        "addCaptions": true,        "title": "string",        "privacyStatus": "private",        "madeForKids": true,        "isShort": true,        "description": "string"      },      "youtubeVisibility": {        "videoId": "string",        "privacyStatus": "private",        "publishAt": "string",        "changedAt": "string"      },      "scheduledAt": "string",      "publishedAt": "string",      "results": [        {          "target": "string",          "label": "string",          "permalink": "string",          "error": "string"        }      ],      "createdAt": "string",      "updatedAt": "string"    }  ]}

{  "error": "string",  "message": "string"}

POST/social/posts

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

`application/json`

curl -X POST "https://example.com/social/posts" \  -H "Content-Type: application/json" \  -d '{    "text": "string",    "targets": [      "string"    ]  }'

{  "postId": "string",  "status": "draft",  "scheduledAt": "string",  "results": [    {      "target": "string",      "label": "string",      "permalink": "string",      "error": "string"    }  ]}

{  "error": "string",  "message": "string"}

GET/social/posts/{postId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

postId*string

Response Body

`application/json`

`application/json`

curl -X GET "https://example.com/social/posts/string"

{  "id": "string",  "status": "draft",  "text": "string",  "targets": [    "string"  ],  "media": [    {      "mediaId": "string",      "url": "string",      "type": "image",      "name": "string"    }  ],  "firstComment": "string",  "youtube": {    "tags": [      "string"    ],    "categoryId": "string",    "notifySubscribers": true,    "embeddable": true,    "publicStatsViewable": true,    "license": "youtube",    "containsSyntheticMedia": true,    "defaultLanguage": "string",    "defaultAudioLanguage": "string",    "recordingDate": "string",    "thumbnailMediaId": "string",    "playlistId": "string",    "addCaptions": true,    "title": "string",    "privacyStatus": "private",    "madeForKids": true,    "isShort": true,    "description": "string"  },  "youtubeVisibility": {    "videoId": "string",    "privacyStatus": "private",    "publishAt": "string",    "changedAt": "string"  },  "scheduledAt": "string",  "publishedAt": "string",  "results": [    {      "target": "string",      "label": "string",      "permalink": "string",      "error": "string"    }  ],  "createdAt": "string",  "updatedAt": "string"}

{  "error": "string",  "message": "string"}

POST/social/posts/{postId}/schedule

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

postId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

`application/json`

curl -X POST "https://example.com/social/posts/string/schedule" \  -H "Content-Type: application/json" \  -d '{    "scheduledAt": "string"  }'

{  "postId": "string",  "status": "draft",  "scheduledAt": "string"}

{  "error": "string",  "message": "string"}

POST/social/posts/{postId}/publish

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

postId*string

Response Body

`application/json`

`application/json`

curl -X POST "https://example.com/social/posts/string/publish"

{  "postId": "string",  "status": "draft",  "results": [    {      "target": "string",      "label": "string",      "permalink": "string",      "error": "string"    }  ]}

{  "error": "string",  "message": "string"}

Change a published YouTube video's visibility

POST/social/posts/{postId}/youtube-visibility

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

postId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

POST /social/posts/:postId/youtube-visibility — the published YouTube video of that post: private / unlisted / public, or a scheduled public release (publishAt with private). Needs the connection's force-ssl grant.

Response Body

`application/json`

`application/json`

curl -X POST "https://example.com/social/posts/string/youtube-visibility" \  -H "Content-Type: application/json" \  -d '{    "privacyStatus": "private"  }'

{  "postId": "string",  "videoId": "string",  "privacyStatus": "private",  "publishAt": "string"}

{  "error": "string",  "message": "string"}

YouTube channel stats

GET/social/youtube/channel

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Response Body

`application/json`

`application/json`

curl -X GET "https://example.com/social/youtube/channel"

{  "channel": {    "channelId": "string",    "title": "string",    "thumbnailUrl": "string",    "subscriberCount": 0,    "viewCount": 0,    "videoCount": 0  },  "recentVideos": [    {      "videoId": "string",      "title": "string",      "publishedAt": "string",      "thumbnailUrl": "string",      "viewCount": 0,      "likeCount": 0,      "commentCount": 0,      "privacyStatus": "private",      "durationSeconds": 0,      "liveStartedAt": "string"    }  ]}

{  "error": "string",  "message": "string"}

YouTube channel analytics, last 28 days

GET/social/youtube/analytics

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Response Body

`application/json`

`application/json`

curl -X GET "https://example.com/social/youtube/analytics"

{  "summary": {    "startDate": "string",    "endDate": "string",    "views": 0,    "watchTimeMinutes": 0,    "averageViewDurationSeconds": 0,    "subscribersGained": 0,    "subscribersLost": 0  },  "days": [    {      "date": "string",      "views": 0,      "watchTimeMinutes": 0    }  ]}

{  "error": "string",  "message": "string"}

List YouTube videos

GET/social/youtube/videos

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Query Parameters

maxResults?integer

Videos per page, 1-50 (default 24)

pageToken?string

nextPageToken of the previous page

Response Body

`application/json`

`application/json`

curl -X GET "https://example.com/social/youtube/videos"

{  "videos": [    {      "videoId": "string",      "title": "string",      "publishedAt": "string",      "thumbnailUrl": "string",      "viewCount": 0,      "likeCount": 0,      "commentCount": 0,      "privacyStatus": "private",      "durationSeconds": 0,      "liveStartedAt": "string"    }  ],  "nextPageToken": "string"}

{  "error": "string",  "message": "string"}

YouTube video stats

GET/social/youtube/videos/{videoId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

videoId*string

Response Body

`application/json`

`application/json`

curl -X GET "https://example.com/social/youtube/videos/string"

{  "video": {    "videoId": "string",    "title": "string",    "publishedAt": "string",    "thumbnailUrl": "string",    "viewCount": 0,    "likeCount": 0,    "commentCount": 0,    "privacyStatus": "private",    "durationSeconds": 0,    "liveStartedAt": "string"  },  "analytics": {    "status": "ok",    "views": 0,    "watchTimeMinutes": 0,    "averageViewDurationSeconds": 0  }}

{  "error": "string",  "message": "string"}

YouTube video transcript

GET/social/youtube/videos/{videoId}/transcript

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

videoId*string

Response Body

`application/json`

`application/json`

curl -X GET "https://example.com/social/youtube/videos/string/transcript"

{  "status": "ok",  "language": "string",  "transcript": "string"}

{  "error": "string",  "message": "string"}

Instagram insights, last 30 days

GET/social/instagram/insights

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Response Body

`application/json`

`application/json`

curl -X GET "https://example.com/social/instagram/insights"

{  "available": true,  "reach": 0,  "views": 0}

{  "error": "string",  "message": "string"}

List Instagram posts

GET/social/instagram/media

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Query Parameters

limit?integer

Items per page, 1-50 (default 24)

after?string

nextCursor of the previous page

Response Body

`application/json`

`application/json`

curl -X GET "https://example.com/social/instagram/media"

{  "items": [    {      "id": "string",      "mediaType": "IMAGE",      "mediaProductType": "FEED",      "mediaUrl": "string",      "thumbnailUrl": "string",      "permalink": "string",      "caption": "string",      "timestamp": "string",      "likeCount": 0,      "commentsCount": 0    }  ],  "nextCursor": "string"}

{  "error": "string",  "message": "string"}

List Threads posts

GET/social/threads/posts

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Response Body

`application/json`

`application/json`

curl -X GET "https://example.com/social/threads/posts"

{  "items": [    {      "id": "string",      "mediaType": "string",      "text": "string",      "mediaUrl": "string",      "thumbnailUrl": "string",      "permalink": "string",      "timestamp": "string"    }  ]}

{  "error": "string",  "message": "string"}

Latest audience snapshot

GET/social/snapshots/latest

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Response Body

`application/json`

`application/json`

curl -X GET "https://example.com/social/snapshots/latest"

{  "snapshot": {    "date": "string",    "counts": {      "youtube": 0,      "instagram": 0,      "facebook": 0,      "linkedin": 0,      "threads": 0,      "tiktok": 0,      "telegram": 0,      "newsletter": 0    },    "source": {      "youtube": "auto",      "instagram": "auto",      "facebook": "auto",      "linkedin": "auto",      "threads": "auto",      "tiktok": "auto",      "telegram": "auto",      "newsletter": "auto"    },    "errors": {      "youtube": "string",      "instagram": "string",      "facebook": "string",      "linkedin": "string",      "threads": "string",      "tiktok": "string",      "telegram": "string",      "newsletter": "string"    },    "updatedAt": "string"  }}

{  "error": "string",  "message": "string"}

Was this article helpful?

Related articles

Spotted something off? Tell us at support@zanfia.com.