Complete Payload Shape
{
"api_name": "SoLoSocialStudio External API",
"version": "v1",
"base_path": "/api/external/v1",
"generated_at": "<runtime-iso-timestamp>",
"auth": {
"api_key_header": "Authorization: Bearer sss_live_... or x-api-key: sss_live_...",
"session_routes": [
{
"method": "GET",
"path": "/api/external/v1/keys"
},
{
"method": "POST",
"path": "/api/external/v1/keys"
},
{
"method": "DELETE",
"path": "/api/external/v1/keys/:id"
},
{
"method": "GET",
"path": "/api/external/v1/connections/:platform/start"
},
{
"method": "GET",
"path": "/api/external/v1/connections/:platform/callback"
},
{
"method": "PUT",
"path": "/api/external/v1/settings/password"
}
]
},
"scope_count": 23,
"route_count": 64,
"resources": [
"ai",
"analytics",
"api-keys",
"audit-logs",
"connections",
"content-folders",
"inbox",
"media-library",
"meta",
"notifications",
"platforms",
"posts",
"review",
"schedule",
"settings",
"uploads",
"webhooks",
"youtube"
],
"scopes": [
{
"name": "*",
"description": "Full access to all external API capabilities."
},
{
"name": "posts:read",
"description": "Read post records and detail payloads."
},
{
"name": "posts:write",
"description": "Create, update, and delete posts."
},
{
"name": "posts:publish",
"description": "Trigger immediate publish_now jobs for posts."
},
{
"name": "analytics:read",
"description": "Read analytics summaries and trend series."
},
{
"name": "schedule:read",
"description": "Read scheduled jobs and queue state."
},
{
"name": "schedule:write",
"description": "Reschedule existing publish jobs."
},
{
"name": "platforms:read",
"description": "Read platform availability and config status."
},
{
"name": "connections:read",
"description": "Read connected account metadata."
},
{
"name": "connections:write",
"description": "Disconnect connected platform accounts."
},
{
"name": "ai:generate",
"description": "Generate captions, images, and videos."
},
{
"name": "media-library:read",
"description": "List media library assets."
},
{
"name": "media-library:write",
"description": "Import and register media assets."
},
{
"name": "inbox:read",
"description": "Read social inbox events and summaries."
},
{
"name": "inbox:write",
"description": "Mark inbox events read/unread."
},
{
"name": "notifications:read",
"description": "Read operational notifications."
},
{
"name": "review:read",
"description": "Read post review approvals and comments."
},
{
"name": "review:write",
"description": "Request/review approvals and post comments."
},
{
"name": "webhooks:read",
"description": "Read outbound webhook endpoints and deliveries."
},
{
"name": "webhooks:write",
"description": "Create/update/delete outbound webhook endpoints."
},
{
"name": "settings:read",
"description": "Read profile and schedule settings."
},
{
"name": "settings:write",
"description": "Update profile and schedule settings."
},
{
"name": "audit-logs:read",
"description": "Read workspace audit logs."
}
],
"routes": [
{
"method": "GET",
"path": "/api/external/v1",
"resource": "meta",
"auth": "none",
"required_scopes": [],
"description": "External API root summary with quick links.",
"internal_equivalent": null
},
{
"method": "GET",
"path": "/api/external/v1/health",
"resource": "meta",
"auth": "none",
"required_scopes": [],
"description": "Health check endpoint.",
"internal_equivalent": null
},
{
"method": "GET",
"path": "/api/external/v1/reference",
"resource": "meta",
"auth": "none",
"required_scopes": [],
"description": "Complete machine-readable route and scope inventory.",
"internal_equivalent": null
},
{
"method": "GET",
"path": "/api/external/v1/whoami",
"resource": "meta",
"auth": "external-api-key",
"required_scopes": [],
"description": "Resolve current API key identity and granted scopes.",
"internal_equivalent": null
},
{
"method": "GET",
"path": "/api/external/v1/posts",
"resource": "posts",
"auth": "external-api-key",
"required_scopes": [
"posts:read"
],
"description": "List posts. Supports folder and tag organization metadata, plus optional ?folder=path/to/folder and ?tag=label filters.",
"internal_equivalent": "/api/posts"
},
{
"method": "POST",
"path": "/api/external/v1/posts",
"resource": "posts",
"auth": "external-api-key",
"required_scopes": [
"posts:write"
],
"description": "Create a post. Supports folder_path, tags, core YouTube upload fields, and publish timing.",
"internal_equivalent": "/api/posts"
},
{
"method": "GET",
"path": "/api/external/v1/posts/:id",
"resource": "posts",
"auth": "external-api-key",
"required_scopes": [
"posts:read"
],
"description": "Get a post by id.",
"internal_equivalent": "/api/posts/:id"
},
{
"method": "PATCH",
"path": "/api/external/v1/posts/:id",
"resource": "posts",
"auth": "external-api-key",
"required_scopes": [
"posts:write"
],
"description": "Update a post, including folder_path and tags metadata, or trigger publish_now (requires posts:publish). For scheduled media, media_url must be an SSS storage_path such as library/<user-id>/<file>; import external URLs through /api/external/v1/media-library first.",
"internal_equivalent": "/api/posts/:id"
},
{
"method": "POST",
"path": "/api/external/v1/posts/:id/publish-now",
"resource": "posts",
"auth": "external-api-key",
"required_scopes": [
"posts:publish"
],
"description": "Queue immediate publish_now execution for a post.",
"internal_equivalent": "/api/posts/:id (PATCH action=publish_now)"
},
{
"method": "DELETE",
"path": "/api/external/v1/posts/:id",
"resource": "posts",
"auth": "external-api-key",
"required_scopes": [
"posts:write"
],
"description": "Delete a post.",
"internal_equivalent": "/api/posts/:id"
},
{
"method": "GET",
"path": "/api/external/v1/content-folders",
"resource": "content-folders",
"auth": "external-api-key",
"required_scopes": [
"posts:read or media-library:read"
],
"description": "List explicit folders for posts or media. Requires ?scope=posts or ?scope=media.",
"internal_equivalent": "/api/content-folders"
},
{
"method": "POST",
"path": "/api/external/v1/content-folders",
"resource": "content-folders",
"auth": "external-api-key",
"required_scopes": [
"posts:write or media-library:write"
],
"description": "Create a folder for posts or media with scope plus either name+parent_path or folder_path.",
"internal_equivalent": "/api/content-folders"
},
{
"method": "GET",
"path": "/api/external/v1/analytics",
"resource": "analytics",
"auth": "external-api-key",
"required_scopes": [
"analytics:read"
],
"description": "Analytics summary and trend data.",
"internal_equivalent": "/api/analytics"
},
{
"method": "GET",
"path": "/api/external/v1/schedule",
"resource": "schedule",
"auth": "external-api-key",
"required_scopes": [
"schedule:read"
],
"description": "List publish jobs and queue state.",
"internal_equivalent": "/api/schedule"
},
{
"method": "GET",
"path": "/api/external/v1/schedule/available-slot",
"resource": "schedule",
"auth": "external-api-key",
"required_scopes": [
"schedule:read"
],
"description": "Find the next best schedule slot.",
"internal_equivalent": "/api/schedule/available-slot"
},
{
"method": "GET",
"path": "/api/external/v1/schedule/missing-content",
"resource": "schedule",
"auth": "external-api-key",
"required_scopes": [
"schedule:read"
],
"description": "List queued jobs with missing media assets.",
"internal_equivalent": "/api/schedule/missing-content"
},
{
"method": "PATCH",
"path": "/api/external/v1/schedule/:id",
"resource": "schedule",
"auth": "external-api-key",
"required_scopes": [
"schedule:write"
],
"description": "Reschedule a queued publish job.",
"internal_equivalent": "/api/schedule/:id"
},
{
"method": "GET",
"path": "/api/external/v1/platforms",
"resource": "platforms",
"auth": "external-api-key",
"required_scopes": [
"platforms:read"
],
"description": "List platform readiness and publish support.",
"internal_equivalent": "/api/platforms"
},
{
"method": "GET",
"path": "/api/external/v1/connections",
"resource": "connections",
"auth": "external-api-key",
"required_scopes": [
"connections:read"
],
"description": "List connected accounts.",
"internal_equivalent": "/api/connections"
},
{
"method": "GET",
"path": "/api/external/v1/connections/:platform/start",
"resource": "connections",
"auth": "session",
"required_scopes": [],
"description": "Start OAuth connect flow for a platform.",
"internal_equivalent": "/api/oauth/:platform/start"
},
{
"method": "GET",
"path": "/api/external/v1/connections/:platform/callback",
"resource": "connections",
"auth": "session",
"required_scopes": [],
"description": "OAuth callback bridge for platform connection flow.",
"internal_equivalent": "/api/oauth/:platform/callback"
},
{
"method": "POST",
"path": "/api/external/v1/connections/:platform",
"resource": "connections",
"auth": "external-api-key",
"required_scopes": [
"connections:write"
],
"description": "Create a manual connection for Bluesky or Mastodon.",
"internal_equivalent": "/api/connections/:platform"
},
{
"method": "DELETE",
"path": "/api/external/v1/connections/:platform",
"resource": "connections",
"auth": "external-api-key",
"required_scopes": [
"connections:write"
],
"description": "Disconnect a platform account.",
"internal_equivalent": "/api/connections/:platform"
},
{
"method": "GET",
"path": "/api/external/v1/notifications",
"resource": "notifications",
"auth": "external-api-key",
"required_scopes": [
"notifications:read"
],
"description": "Read queue/token/publish notifications and summary counts.",
"internal_equivalent": "/api/notifications"
},
{
"method": "GET",
"path": "/api/external/v1/inbox",
"resource": "inbox",
"auth": "external-api-key",
"required_scopes": [
"inbox:read"
],
"description": "Read social inbox events.",
"internal_equivalent": "/api/inbox"
},
{
"method": "PATCH",
"path": "/api/external/v1/inbox",
"resource": "inbox",
"auth": "external-api-key",
"required_scopes": [
"inbox:write"
],
"description": "Mark inbox events read/unread.",
"internal_equivalent": "/api/inbox"
},
{
"method": "GET",
"path": "/api/external/v1/media-library",
"resource": "media-library",
"auth": "external-api-key",
"required_scopes": [
"media-library:read"
],
"description": "List media library items. Supports folder and tag organization metadata, plus optional ?folder=path/to/folder and ?tag=label filters.",
"internal_equivalent": "/api/media-library"
},
{
"method": "POST",
"path": "/api/external/v1/media-library",
"resource": "media-library",
"auth": "external-api-key",
"required_scopes": [
"media-library:write"
],
"description": "Import/register media library items. Supports tags and folder_path metadata. Use source_url to fetch a remote asset into SSS storage, then use the returned storage_path as media_url on post create/update.",
"internal_equivalent": "/api/media-library"
},
{
"method": "PATCH",
"path": "/api/external/v1/media-library",
"resource": "media-library",
"auth": "external-api-key",
"required_scopes": [
"media-library:write"
],
"description": "Bulk update media library tags and folder_path metadata by passing id or ids.",
"internal_equivalent": "/api/media-library"
},
{
"method": "GET",
"path": "/api/external/v1/review/approvals",
"resource": "review",
"auth": "external-api-key",
"required_scopes": [
"review:read"
],
"description": "List review approvals.",
"internal_equivalent": "/api/review/approvals"
},
{
"method": "POST",
"path": "/api/external/v1/review/approvals",
"resource": "review",
"auth": "external-api-key",
"required_scopes": [
"review:write"
],
"description": "Create a review approval request.",
"internal_equivalent": "/api/review/approvals"
},
{
"method": "PATCH",
"path": "/api/external/v1/review/approvals/:id",
"resource": "review",
"auth": "external-api-key",
"required_scopes": [
"review:write"
],
"description": "Approve, reject, request changes, or cancel an approval.",
"internal_equivalent": "/api/review/approvals/:id"
},
{
"method": "GET",
"path": "/api/external/v1/review/comments",
"resource": "review",
"auth": "external-api-key",
"required_scopes": [
"review:read"
],
"description": "List review comments for a post.",
"internal_equivalent": "/api/review/comments"
},
{
"method": "POST",
"path": "/api/external/v1/review/comments",
"resource": "review",
"auth": "external-api-key",
"required_scopes": [
"review:write"
],
"description": "Create a review comment for a post.",
"internal_equivalent": "/api/review/comments"
},
{
"method": "DELETE",
"path": "/api/external/v1/schedule/attempts",
"resource": "schedule",
"auth": "external-api-key",
"required_scopes": [
"schedule:write"
],
"description": "Clear recent publish attempts by scope (failed or all). This does not delete historical canceled schedule jobs/rows.",
"internal_equivalent": "/api/schedule/attempts"
},
{
"method": "GET",
"path": "/api/external/v1/settings",
"resource": "settings",
"auth": "external-api-key",
"required_scopes": [
"settings:read"
],
"description": "Read profile and schedule settings.",
"internal_equivalent": "/api/settings"
},
{
"method": "PUT",
"path": "/api/external/v1/settings",
"resource": "settings",
"auth": "external-api-key",
"required_scopes": [
"settings:write"
],
"description": "Update profile and schedule settings.",
"internal_equivalent": "/api/settings"
},
{
"method": "PUT",
"path": "/api/external/v1/settings/password",
"resource": "settings",
"auth": "session",
"required_scopes": [],
"description": "Update the current user's password.",
"internal_equivalent": "/api/settings/password"
},
{
"method": "GET",
"path": "/api/external/v1/audit-logs",
"resource": "audit-logs",
"auth": "external-api-key",
"required_scopes": [
"audit-logs:read"
],
"description": "Read workspace audit logs.",
"internal_equivalent": "/api/audit-logs"
},
{
"method": "POST",
"path": "/api/external/v1/ai/caption",
"resource": "ai",
"auth": "external-api-key",
"required_scopes": [
"ai:generate"
],
"description": "Generate text captions.",
"internal_equivalent": "/api/ai/caption"
},
{
"method": "POST",
"path": "/api/external/v1/ai/image",
"resource": "ai",
"auth": "external-api-key",
"required_scopes": [
"ai:generate"
],
"description": "Generate image assets and store to media library.",
"internal_equivalent": "/api/ai/image"
},
{
"method": "POST",
"path": "/api/external/v1/ai/video",
"resource": "ai",
"auth": "external-api-key",
"required_scopes": [
"ai:generate"
],
"description": "Start AI video generation operation.",
"internal_equivalent": "/api/ai/video"
},
{
"method": "GET",
"path": "/api/external/v1/ai/video",
"resource": "ai",
"auth": "external-api-key",
"required_scopes": [
"ai:generate"
],
"description": "Poll AI video generation operation.",
"internal_equivalent": "/api/ai/video"
},
{
"method": "GET",
"path": "/api/external/v1/youtube/playlists",
"resource": "youtube",
"auth": "external-api-key",
"required_scopes": [
"posts:read"
],
"description": "Advanced YouTube workspace route for playlist lookup on the connected account. Not required for the standard hosted YouTube publishing flow.",
"internal_equivalent": null
},
{
"method": "POST",
"path": "/api/external/v1/youtube/playlists",
"resource": "youtube",
"auth": "external-api-key",
"required_scopes": [
"posts:write"
],
"description": "Advanced YouTube workspace route for playlist placement. Required: 'video_id', 'playlist_id'. Not required for the standard hosted YouTube publishing flow.",
"internal_equivalent": null
},
{
"method": "POST",
"path": "/api/external/v1/youtube/comments",
"resource": "youtube",
"auth": "external-api-key",
"required_scopes": [
"posts:write"
],
"description": "Advanced YouTube workspace route for comment publishing. Required: 'video_id', 'text'. Not required for the standard hosted YouTube publishing flow.",
"internal_equivalent": null
},
{
"method": "PATCH",
"path": "/api/external/v1/youtube/videos",
"resource": "youtube",
"auth": "external-api-key",
"required_scopes": [
"posts:write"
],
"description": "Advanced YouTube workspace route for video metadata updates. Required: 'video_id', 'snippet'. Not required for the standard hosted YouTube publishing flow.",
"internal_equivalent": null
},
{
"method": "DELETE",
"path": "/api/external/v1/youtube/videos",
"resource": "youtube",
"auth": "external-api-key",
"required_scopes": [
"posts:write"
],
"description": "Advanced YouTube workspace route for video deletion. Required parameter: 'video_id'. Not required for the standard hosted YouTube publishing flow.",
"internal_equivalent": null
},
{
"method": "GET",
"path": "/api/external/v1/youtube/channel",
"resource": "youtube",
"auth": "external-api-key",
"required_scopes": [
"connections:read"
],
"description": "Get connected YouTube channel metadata and basic statistics used by the hosted publishing flow.",
"internal_equivalent": null
},
{
"method": "GET",
"path": "/api/external/v1/youtube/captions",
"resource": "youtube",
"auth": "external-api-key",
"required_scopes": [
"posts:read"
],
"description": "Advanced YouTube workspace route for caption lookup. Required parameter: 'video_id'. Not required for the standard hosted YouTube publishing flow.",
"internal_equivalent": null
},
{
"method": "DELETE",
"path": "/api/external/v1/youtube/captions",
"resource": "youtube",
"auth": "external-api-key",
"required_scopes": [
"posts:write"
],
"description": "Advanced YouTube workspace route for caption deletion. Required parameters: 'video_id', 'caption_id'. Not required for the standard hosted YouTube publishing flow.",
"internal_equivalent": null
},
{
"method": "POST",
"path": "/api/external/v1/youtube/videos/thumbnail",
"resource": "youtube",
"auth": "external-api-key",
"required_scopes": [
"posts:write"
],
"description": "Advanced YouTube workspace route for custom thumbnails. Required: 'video_id', 'media_url'. Not required for the standard hosted YouTube publishing flow.",
"internal_equivalent": null
},
{
"method": "POST",
"path": "/api/external/v1/youtube/live",
"resource": "youtube",
"auth": "external-api-key",
"required_scopes": [
"posts:write"
],
"description": "Advanced YouTube workspace route for Live Broadcast and Stream management. Required: 'action'. Supports 'create_broadcast', 'create_stream', 'bind', 'transition', 'chat_post'. Not required for the standard hosted YouTube publishing flow.",
"internal_equivalent": null
},
{
"method": "GET",
"path": "/api/external/v1/youtube/live",
"resource": "youtube",
"auth": "external-api-key",
"required_scopes": [
"posts:read"
],
"description": "Advanced YouTube workspace route for YouTube Live data retrieval. Action 'chat_list' requires 'live_chat_id'. Not required for the standard hosted YouTube publishing flow.",
"internal_equivalent": null
},
{
"method": "GET",
"path": "/api/external/v1/youtube/search",
"resource": "youtube",
"auth": "external-api-key",
"required_scopes": [
"posts:read"
],
"description": "Advanced YouTube workspace route for YouTube search across videos, channels, or playlists. Required: 'q'. Not required for the standard hosted YouTube publishing flow.",
"internal_equivalent": null
},
{
"method": "POST",
"path": "/api/external/v1/youtube/interact",
"resource": "youtube",
"auth": "external-api-key",
"required_scopes": [
"posts:write"
],
"description": "Advanced YouTube workspace route for content interaction. Required: 'action', 'target_id'. Actions: 'like', 'rate', 'subscribe'. Not required for the standard hosted YouTube publishing flow.",
"internal_equivalent": null
},
{
"method": "POST",
"path": "/api/external/v1/uploads/posts/sign",
"resource": "uploads",
"auth": "external-api-key",
"required_scopes": [
"posts:write"
],
"description": "Create signed upload URL for post assets.",
"internal_equivalent": null
},
{
"method": "GET",
"path": "/api/external/v1/webhooks/outbound",
"resource": "webhooks",
"auth": "external-api-key",
"required_scopes": [
"webhooks:read"
],
"description": "List outbound webhooks and recent deliveries.",
"internal_equivalent": "/api/webhooks/outbound"
},
{
"method": "POST",
"path": "/api/external/v1/webhooks/outbound",
"resource": "webhooks",
"auth": "external-api-key",
"required_scopes": [
"webhooks:write"
],
"description": "Create outbound webhook endpoint.",
"internal_equivalent": "/api/webhooks/outbound"
},
{
"method": "PATCH",
"path": "/api/external/v1/webhooks/outbound/:id",
"resource": "webhooks",
"auth": "external-api-key",
"required_scopes": [
"webhooks:write"
],
"description": "Update outbound webhook endpoint.",
"internal_equivalent": "/api/webhooks/outbound/:id"
},
{
"method": "DELETE",
"path": "/api/external/v1/webhooks/outbound/:id",
"resource": "webhooks",
"auth": "external-api-key",
"required_scopes": [
"webhooks:write"
],
"description": "Delete outbound webhook endpoint.",
"internal_equivalent": "/api/webhooks/outbound/:id"
},
{
"method": "GET",
"path": "/api/external/v1/keys",
"resource": "api-keys",
"auth": "session",
"required_scopes": [],
"description": "List API keys for current user.",
"internal_equivalent": "/api/external/v1/keys"
},
{
"method": "POST",
"path": "/api/external/v1/keys",
"resource": "api-keys",
"auth": "session",
"required_scopes": [],
"description": "Create API key for current user.",
"internal_equivalent": "/api/external/v1/keys"
},
{
"method": "DELETE",
"path": "/api/external/v1/keys/:id",
"resource": "api-keys",
"auth": "session",
"required_scopes": [],
"description": "Revoke API key for current user.",
"internal_equivalent": "/api/external/v1/keys/:id"
}
],
"internal_exclusions": [
{
"method": "GET",
"path": "/api/auth/callback",
"reason": "Supabase auth redirect callback used by browser login flows."
},
{
"method": "GET",
"path": "/api/publish/run",
"reason": "Internal publish runner endpoint guarded by PUBLISH_RUNNER_SECRET."
},
{
"method": "GET",
"path": "/api/webhooks/meta",
"reason": "Inbound Meta verification webhook endpoint."
},
{
"method": "POST",
"path": "/api/webhooks/meta",
"reason": "Inbound Meta webhook delivery endpoint."
},
{
"method": "GET",
"path": "/api/connections/verify",
"reason": "Session-auth route used by the dashboard to verify connected account tokens."
},
{
"method": "GET",
"path": "/api/settings/platform-oauth/:platform",
"reason": "Session-auth settings route for managing per-user platform OAuth client credentials."
},
{
"method": "PUT",
"path": "/api/settings/platform-oauth/:platform",
"reason": "Session-auth settings route for saving per-user platform OAuth client credentials."
},
{
"method": "DELETE",
"path": "/api/settings/platform-oauth/:platform",
"reason": "Session-auth settings route for removing per-user platform OAuth client credentials."
}
]
}