Developer Docs

SoLoSocial External API

Full route, scope, and auth reference for automating every core SoLoSocialStudio workflow via API.

Base: /api/external/v1
Open Agent ReferenceOpen API ReferenceManage API KeysManage Webhooks

Hosted YouTube Footprint

The standard hosted YouTube OAuth flow currently covers connecting a creator's channel, uploading videos, and reading basic channel or video statistics such as views, likes, and comments. Additional YouTube routes documented below support advanced workspace automation and are not required for the standard hosted publishing experience.

Authentication

External routes use API key auth. Key lifecycle routes are session-auth only.

Authorization: Bearer sss_live_xxxxxxxxxxxxxxxxxxxxxxxx
x-api-key: sss_live_xxxxxxxxxxxxxxxxxxxxxxxx

Session key lifecycle: GET/POST /api/external/v1/keys, DELETE /api/external/v1/keys/:id.
Session OAuth connect: GET /api/external/v1/connections/:platform/start.
Session password update: PUT /api/external/v1/settings/password.

Coverage

Routes

64

Scopes

23

Reference Endpoint

GET /api/external/v1/reference

Internal Service-Only Routes

GET/api/auth/callback

Supabase auth redirect callback used by browser login flows.

GET/api/publish/run

Internal publish runner endpoint guarded by PUBLISH_RUNNER_SECRET.

GET/api/webhooks/meta

Inbound Meta verification webhook endpoint.

POST/api/webhooks/meta

Inbound Meta webhook delivery endpoint.

GET/api/connections/verify

Session-auth route used by the dashboard to verify connected account tokens.

GET/api/settings/platform-oauth/:platform

Session-auth settings route for managing per-user platform OAuth client credentials.

PUT/api/settings/platform-oauth/:platform

Session-auth settings route for saving per-user platform OAuth client credentials.

DELETE/api/settings/platform-oauth/:platform

Session-auth settings route for removing per-user platform OAuth client credentials.

Scopes

*

Full access to all external API capabilities.

posts:read

Read post records and detail payloads.

posts:write

Create, update, and delete posts.

posts:publish

Trigger immediate publish_now jobs for posts.

analytics:read

Read analytics summaries and trend series.

schedule:read

Read scheduled jobs and queue state.

schedule:write

Reschedule existing publish jobs.

platforms:read

Read platform availability and config status.

connections:read

Read connected account metadata.

connections:write

Disconnect connected platform accounts.

ai:generate

Generate captions, images, and videos.

media-library:read

List media library assets.

media-library:write

Import and register media assets.

inbox:read

Read social inbox events and summaries.

inbox:write

Mark inbox events read/unread.

notifications:read

Read operational notifications.

review:read

Read post review approvals and comments.

review:write

Request/review approvals and post comments.

webhooks:read

Read outbound webhook endpoints and deliveries.

webhooks:write

Create/update/delete outbound webhook endpoints.

settings:read

Read profile and schedule settings.

settings:write

Update profile and schedule settings.

audit-logs:read

Read workspace audit logs.

ai

POST/api/external/v1/ai/caption

external-api-key

ai:generate

Generate text captions.

App parity: /api/ai/caption

POST/api/external/v1/ai/image

external-api-key

ai:generate

Generate image assets and store to media library.

App parity: /api/ai/image

POST/api/external/v1/ai/video

external-api-key

ai:generate

Start AI video generation operation.

App parity: /api/ai/video

GET/api/external/v1/ai/video

external-api-key

ai:generate

Poll AI video generation operation.

App parity: /api/ai/video

analytics

GET/api/external/v1/analytics

external-api-key

analytics:read

Analytics summary and trend data.

App parity: /api/analytics

api-keys

GET/api/external/v1/keys

session

none

List API keys for current user.

App parity: /api/external/v1/keys

POST/api/external/v1/keys

session

none

Create API key for current user.

App parity: /api/external/v1/keys

DELETE/api/external/v1/keys/:id

session

none

Revoke API key for current user.

App parity: /api/external/v1/keys/:id

audit-logs

GET/api/external/v1/audit-logs

external-api-key

audit-logs:read

Read workspace audit logs.

App parity: /api/audit-logs

connections

GET/api/external/v1/connections

external-api-key

connections:read

List connected accounts.

App parity: /api/connections

GET/api/external/v1/connections/:platform/start

session

none

Start OAuth connect flow for a platform.

App parity: /api/oauth/:platform/start

GET/api/external/v1/connections/:platform/callback

session

none

OAuth callback bridge for platform connection flow.

App parity: /api/oauth/:platform/callback

POST/api/external/v1/connections/:platform

external-api-key

connections:write

Create a manual connection for Bluesky or Mastodon.

App parity: /api/connections/:platform

DELETE/api/external/v1/connections/:platform

external-api-key

connections:write

Disconnect a platform account.

App parity: /api/connections/:platform

content-folders

GET/api/external/v1/content-folders

external-api-key

posts:read or media-library:read

List explicit folders for posts or media. Requires ?scope=posts or ?scope=media.

App parity: /api/content-folders

POST/api/external/v1/content-folders

external-api-key

posts:write or media-library:write

Create a folder for posts or media with scope plus either name+parent_path or folder_path.

App parity: /api/content-folders

inbox

GET/api/external/v1/inbox

external-api-key

inbox:read

Read social inbox events.

App parity: /api/inbox

PATCH/api/external/v1/inbox

external-api-key

inbox:write

Mark inbox events read/unread.

App parity: /api/inbox

media-library

GET/api/external/v1/media-library

external-api-key

media-library:read

List media library items. Supports folder and tag organization metadata, plus optional ?folder=path/to/folder and ?tag=label filters.

App parity: /api/media-library

POST/api/external/v1/media-library

external-api-key

media-library:write

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.

App parity: /api/media-library

PATCH/api/external/v1/media-library

external-api-key

media-library:write

Bulk update media library tags and folder_path metadata by passing id or ids.

App parity: /api/media-library

meta

GET/api/external/v1

none

none

External API root summary with quick links.

GET/api/external/v1/health

none

none

Health check endpoint.

GET/api/external/v1/reference

none

none

Complete machine-readable route and scope inventory.

GET/api/external/v1/whoami

external-api-key

none

Resolve current API key identity and granted scopes.

notifications

GET/api/external/v1/notifications

external-api-key

notifications:read

Read queue/token/publish notifications and summary counts.

App parity: /api/notifications

platforms

GET/api/external/v1/platforms

external-api-key

platforms:read

List platform readiness and publish support.

App parity: /api/platforms

posts

GET/api/external/v1/posts

external-api-key

posts:read

List posts. Supports folder and tag organization metadata, plus optional ?folder=path/to/folder and ?tag=label filters.

App parity: /api/posts

POST/api/external/v1/posts

external-api-key

posts:write

Create a post. Supports folder_path, tags, core YouTube upload fields, and publish timing.

App parity: /api/posts

GET/api/external/v1/posts/:id

external-api-key

posts:read

Get a post by id.

App parity: /api/posts/:id

PATCH/api/external/v1/posts/:id

external-api-key

posts:write

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.

App parity: /api/posts/:id

POST/api/external/v1/posts/:id/publish-now

external-api-key

posts:publish

Queue immediate publish_now execution for a post.

App parity: /api/posts/:id (PATCH action=publish_now)

DELETE/api/external/v1/posts/:id

external-api-key

posts:write

Delete a post.

App parity: /api/posts/:id

review

GET/api/external/v1/review/approvals

external-api-key

review:read

List review approvals.

App parity: /api/review/approvals

POST/api/external/v1/review/approvals

external-api-key

review:write

Create a review approval request.

App parity: /api/review/approvals

PATCH/api/external/v1/review/approvals/:id

external-api-key

review:write

Approve, reject, request changes, or cancel an approval.

App parity: /api/review/approvals/:id

GET/api/external/v1/review/comments

external-api-key

review:read

List review comments for a post.

App parity: /api/review/comments

POST/api/external/v1/review/comments

external-api-key

review:write

Create a review comment for a post.

App parity: /api/review/comments

schedule

GET/api/external/v1/schedule

external-api-key

schedule:read

List publish jobs and queue state.

App parity: /api/schedule

GET/api/external/v1/schedule/available-slot

external-api-key

schedule:read

Find the next best schedule slot.

App parity: /api/schedule/available-slot

GET/api/external/v1/schedule/missing-content

external-api-key

schedule:read

List queued jobs with missing media assets.

App parity: /api/schedule/missing-content

PATCH/api/external/v1/schedule/:id

external-api-key

schedule:write

Reschedule a queued publish job.

App parity: /api/schedule/:id

DELETE/api/external/v1/schedule/attempts

external-api-key

schedule:write

Clear recent publish attempts by scope (failed or all). This does not delete historical canceled schedule jobs/rows.

App parity: /api/schedule/attempts

settings

GET/api/external/v1/settings

external-api-key

settings:read

Read profile and schedule settings.

App parity: /api/settings

PUT/api/external/v1/settings

external-api-key

settings:write

Update profile and schedule settings.

App parity: /api/settings

PUT/api/external/v1/settings/password

session

none

Update the current user's password.

App parity: /api/settings/password

uploads

POST/api/external/v1/uploads/posts/sign

external-api-key

posts:write

Create signed upload URL for post assets.

webhooks

GET/api/external/v1/webhooks/outbound

external-api-key

webhooks:read

List outbound webhooks and recent deliveries.

App parity: /api/webhooks/outbound

POST/api/external/v1/webhooks/outbound

external-api-key

webhooks:write

Create outbound webhook endpoint.

App parity: /api/webhooks/outbound

PATCH/api/external/v1/webhooks/outbound/:id

external-api-key

webhooks:write

Update outbound webhook endpoint.

App parity: /api/webhooks/outbound/:id

DELETE/api/external/v1/webhooks/outbound/:id

external-api-key

webhooks:write

Delete outbound webhook endpoint.

App parity: /api/webhooks/outbound/:id

youtube

GET/api/external/v1/youtube/playlists

external-api-key

posts:read

Advanced YouTube workspace route for playlist lookup on the connected account. Not required for the standard hosted YouTube publishing flow.

POST/api/external/v1/youtube/playlists

external-api-key

posts:write

Advanced YouTube workspace route for playlist placement. Required: 'video_id', 'playlist_id'. Not required for the standard hosted YouTube publishing flow.

POST/api/external/v1/youtube/comments

external-api-key

posts:write

Advanced YouTube workspace route for comment publishing. Required: 'video_id', 'text'. Not required for the standard hosted YouTube publishing flow.

PATCH/api/external/v1/youtube/videos

external-api-key

posts:write

Advanced YouTube workspace route for video metadata updates. Required: 'video_id', 'snippet'. Not required for the standard hosted YouTube publishing flow.

DELETE/api/external/v1/youtube/videos

external-api-key

posts:write

Advanced YouTube workspace route for video deletion. Required parameter: 'video_id'. Not required for the standard hosted YouTube publishing flow.

GET/api/external/v1/youtube/channel

external-api-key

connections:read

Get connected YouTube channel metadata and basic statistics used by the hosted publishing flow.

GET/api/external/v1/youtube/captions

external-api-key

posts:read

Advanced YouTube workspace route for caption lookup. Required parameter: 'video_id'. Not required for the standard hosted YouTube publishing flow.

DELETE/api/external/v1/youtube/captions

external-api-key

posts:write

Advanced YouTube workspace route for caption deletion. Required parameters: 'video_id', 'caption_id'. Not required for the standard hosted YouTube publishing flow.

POST/api/external/v1/youtube/videos/thumbnail

external-api-key

posts:write

Advanced YouTube workspace route for custom thumbnails. Required: 'video_id', 'media_url'. Not required for the standard hosted YouTube publishing flow.

POST/api/external/v1/youtube/live

external-api-key

posts:write

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.

GET/api/external/v1/youtube/live

external-api-key

posts:read

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.

GET/api/external/v1/youtube/search

external-api-key

posts:read

Advanced YouTube workspace route for YouTube search across videos, channels, or playlists. Required: 'q'. Not required for the standard hosted YouTube publishing flow.

POST/api/external/v1/youtube/interact

external-api-key

posts:write

Advanced YouTube workspace route for content interaction. Required: 'action', 'target_id'. Actions: 'like', 'rate', 'subscribe'. Not required for the standard hosted YouTube publishing flow.

Quickstart: Attach Scheduled Media
# 1) Import external media into SSS storage
curl -X POST "$APP_URL/api/external/v1/media-library" \
  -H "Authorization: Bearer $SSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://example.com/image.jpg"
  }'

# Response includes: item.storage_path

# 2) PATCH the post using that storage_path, not the public URL
curl -X PATCH "$APP_URL/api/external/v1/posts/<post_id>" \
  -H "Authorization: Bearer $SSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "media_url": "library/<user-id>/<imported-file>.jpg"
  }'
Quickstart: Create Key
curl -X POST "$APP_URL/api/external/v1/keys" \
  -H "Authorization: Bearer <supabase_session_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Automation Worker",
    "scopes": ["posts:read", "posts:write", "analytics:read", "schedule:read"]
  }'
Quickstart: Reference Payload
curl -X GET "$APP_URL/api/external/v1/reference"

# route_count, scope_count, routes[], scopes[]
# use this for runtime capability discovery in AI agents