Return up to 50 recent posts or videos per platform for the current workspace. Data is unified into the same post shape across LinkedIn, Facebook, Instagram, TikTok, YouTube, Threads, Pinterest, and Bluesky.
Base URL & auth
https://backend.postsiva.com
curl "https://backend.postsiva.com/unified/posts?limit=10&stats=true" \
-H "X-API-Key: psk_live_YOUR_KEY"
| Header | Required | Notes |
|---|
X-API-Key | Yes (or Bearer) | Workspace from key. See Authentication. |
X-Workspace-Id | JWT only | Required with JWT login |
Omit platforms to return slices for all connected accounts (token-presence scan, plus Threads). Unsupported platform names return 400.
GET /unified/posts
Query parameters
| Parameter | Type | Default | Description |
|---|
limit | integer | 10 | Posts per platform, 1–50 |
stats | boolean | true | Include per-post engagement where supported (LinkedIn stats API, etc.) |
refresh_posts | boolean | false | Pull latest post/media lists from platform APIs where supported |
refresh_stats | boolean | false | Refresh per-post insights/stats where supported |
platforms | string[] | all connected | Filter: linkedin, facebook, instagram, tiktok, youtube, threads, pinterest, bluesky |
facebook_page_ids | string[] | — | Only fetch/return posts from these Facebook Page IDs |
linkedin_organization_ids | string[] | — | Include org/page posts for these LinkedIn organization IDs (URN or numeric) |
board_id | string | — | Pinterest board id — fetch pins only from this board |
?platforms=linkedin&platforms=facebook.
curl -G "https://backend.postsiva.com/unified/posts" \
-H "X-API-Key: psk_live_YOUR_KEY" \
--data-urlencode "limit=20" \
--data-urlencode "refresh_posts=true" \
--data-urlencode "platforms=linkedin" \
--data-urlencode "platforms=instagram" \
--data-urlencode "linkedin_organization_ids=10987654321"
Response structure
Top-level fields:
| Field | Description |
|---|
success | true on success |
message | Optional human-readable summary |
source | e.g. fetched — connection flags match GET /unified/oauth/token |
last_updated | Newest platform refresh timestamp (ISO) |
linkedin, facebook, instagram, tiktok, youtube, threads, pinterest, bluesky.
| Field | Description |
|---|
posts | Array of unified post objects |
source | redis_cache, database, or api |
last_updated | ISO timestamp for this platform |
message | Optional status from platform service |
error | Set when fetch failed for this platform |
platform_meta | Extra platform-specific data (e.g. Facebook pages list) |
Unified post object
Every platform returns the same shape:
| Field | Type | Description |
|---|
post_id | string | Platform-native post or video id |
commentary | string | Caption, message, or description |
published_at | string | ISO publish time |
type | string | image, video, text, or carousel |
images | object[] | { url, width?, height? } |
videos | object | { videoUrl, thumbnailUrl } or null |
permalink | string | Public link to the post |
like_count | integer | Likes/reactions (0 if unavailable) |
comment_count | integer | Comments/replies |
share_count | integer | Shares |
impression_count | integer | Impressions/views |
source_page_id | string | Facebook page or LinkedIn org id when relevant |
ai_watcher_enabled | boolean | AI comment watcher enabled for this post |
Example response
{
"success": true,
"source": "fetched",
"last_updated": "2026-07-08T12:00:00Z",
"linkedin": {
"posts": [
{
"post_id": "urn:li:share:7123456789012345678",
"commentary": "Launch day thread 🚀",
"published_at": "2026-07-01T09:00:00Z",
"type": "text",
"images": [],
"videos": null,
"permalink": "https://www.linkedin.com/feed/update/...",
"like_count": 42,
"comment_count": 5,
"share_count": 3,
"impression_count": 1200,
"source_page_id": null,
"ai_watcher_enabled": false
}
],
"source": "database",
"last_updated": "2026-07-08T11:55:00Z"
},
"instagram": {
"posts": [],
"source": "api",
"message": "Refreshed from Instagram Graph API"
}
}
GET /unified/posts/
Fetch a single post with force refresh. Requires query params:
| Parameter | Required | Description |
|---|
platform | Yes | Platform name |
organization_id | LinkedIn org posts | LinkedIn organization id |
page_id | Facebook page posts | Facebook page id |
API key scope: linkedin_posts
Keys with scope linkedin_posts are read-only and restricted to GET /unified/posts (LinkedIn data only). They cannot call posting, OAuth, or other write endpoints. Refresh behavior
| Flag | Effect |
|---|
refresh_posts=false | Prefer cached/DB lists (faster) |
refresh_posts=true | Call platform APIs to update post lists where supported |
refresh_stats=true | Refresh per-post metrics (may use DB-backed posts as input) |
When platforms=["linkedin"] with no org ids and refresh_posts=true, live LinkedIn personal refresh is expensive (Apify) and limit is capped at 2. Prefer cached data unless you explicitly need a live sync.
stats flag does not strip TikTok like/comment/view fields.
MCP equivalent
| MCP tool | REST |
|---|
get_user_posts | GET /unified/posts |
limit, refresh_posts, refresh_stats, platforms, Facebook page ids, LinkedIn org ids.
Connect at https://mcp.postsiva.com/mcp — see MCP tools.
- Analytics — workspace totals from stored metrics (no live API fan-out)
- Comments — comments on recent posts
- Posting — create new posts
- OAuth — connection status drives which platforms appear