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

Brand Scoping

Brand-scoped API-key routes use the first accessible/default brand unless clients pass a valid x-solo-brand-id or ?brand_id=.... Discover IDs with GET /api/external/v1/brands; the dashboard active brand is browser-session state.

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

72

Scopes

24

Features

17

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/auth/me

Session-auth identity route for browser UI state; external callers use GET /api/external/v1/whoami.

GET/api/auth/sign-in

Logto browser sign-in redirect route, not an API-key automation endpoint.

GET/api/auth/sign-out

Logto browser sign-out redirect route, not an API-key automation endpoint.

GET/api/publish/run

Internal publish runner endpoint guarded by PUBLISH_RUNNER_SECRET.

POST/api/storage/upload

Session-auth raw storage upload helper; external callers use POST /api/external/v1/media-library or POST /api/external/v1/uploads/posts/sign.

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.

POST/api/brands

Dashboard brand creation changes workspace structure and active browser state; external callers should use GET /api/external/v1/brands for discovery.

PATCH/api/brands

Dashboard active-brand switching is browser-session state; external callers scope requests with x-solo-brand-id or brand_id.

DELETE/api/brands

Brand deletion is destructive and requires the dashboard confirmation flow.

POST/api/brands/move-schedule

Schedule migration between brands is a dashboard recovery action that requires careful review before moving jobs.

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.

App Feature Coverage

Dashboard feature coverage mapped to external API resources and intentionally session-only/internal areas.

Dashboard Overview

/dashboard

covered

Resources: analytics, schedule, posts, connections, platforms

Dashboard summary widgets are represented by read routes for analytics, publishing schedule, drafts/posts, connected accounts, and supported platforms.

Documented routes: GET /api/external/v1/analytics, GET /api/external/v1/schedule, GET /api/external/v1/posts, GET /api/external/v1/connections, GET /api/external/v1/platforms

Post Composer and Post Library

/dashboard/posts, /dashboard/posts/new

covered

Resources: posts, content-folders, media-library, ai, schedule, uploads, review, platforms, connections

Create/edit/delete posts, attach stored media, generate AI captions/images/videos, inspect AI usage/budget visibility, organize post folders, reserve schedule slots, submit approvals, and publish immediately.

Documented routes: GET /api/external/v1/posts, POST /api/external/v1/posts, GET /api/external/v1/posts/:id, PATCH /api/external/v1/posts/:id, POST /api/external/v1/posts/:id/publish-now, +17 more

Publishing Schedule

/dashboard/schedule

covered

Resources: schedule

Calendar list, next-slot lookup, missing-content diagnostics, job updates, and publish-attempt cleanup are represented.

Documented routes: GET /api/external/v1/schedule, GET /api/external/v1/schedule/available-slot, GET /api/external/v1/schedule/missing-content, PATCH /api/external/v1/schedule/:id, DELETE /api/external/v1/schedule/:id, +1 more

Analytics

/dashboard/analytics

covered

Resources: analytics

External clients can request the same analytics aggregate used by the dashboard.

Documented routes: GET /api/external/v1/analytics

Social Connections

/dashboard/connections

covered

Resources: platforms, connections

Connection listing, Meta page selection, interactive OAuth start/callback, manual Bluesky/Mastodon setup, and disconnect are covered. Per-user OAuth client settings and token verification remain session-only internal routes.

Documented routes: GET /api/external/v1/platforms, GET /api/external/v1/connections, GET /api/external/v1/connections/meta-pages, GET /api/external/v1/connections/:platform/start, GET /api/external/v1/connections/:platform/callback, +3 more

Media Library

/dashboard/media-library

covered

Resources: media-library, content-folders, ai, uploads

List/import/register/update/delete media, manage media folders, request signed uploads, generate media assets, and inspect AI video usage/budget visibility.

Documented routes: GET /api/external/v1/media-library, POST /api/external/v1/media-library, PATCH /api/external/v1/media-library, DELETE /api/external/v1/media-library, GET /api/external/v1/content-folders, +8 more

Inbox

/dashboard/inbox

covered

Resources: inbox

Read and update inbox/conversation items.

Documented routes: GET /api/external/v1/inbox, PATCH /api/external/v1/inbox

Notifications

/dashboard/notifications, components/layout/Navbar

covered

Resources: notifications

Full notification lists and dashboard summary counts are available through the notifications resource.

Documented routes: GET /api/external/v1/notifications

Review and Approvals

/dashboard/review, /dashboard/posts

covered

Resources: review

Approval queue, approval state changes, and review comments are represented.

Documented routes: GET /api/external/v1/review/approvals, POST /api/external/v1/review/approvals, PATCH /api/external/v1/review/approvals/:id, GET /api/external/v1/review/comments, POST /api/external/v1/review/comments

Outbound Webhooks

/dashboard/webhooks

covered

Resources: webhooks

List/create/update/delete outbound webhook endpoints and inspect recent deliveries.

Documented routes: GET /api/external/v1/webhooks/outbound, POST /api/external/v1/webhooks/outbound, PATCH /api/external/v1/webhooks/outbound/:id, DELETE /api/external/v1/webhooks/outbound/:id

API Keys

/dashboard/api-keys

session-only

Resources: api-keys

Key lifecycle is intentionally session-authenticated so API keys cannot mint or revoke other API keys.

Documented routes: GET /api/external/v1/keys, POST /api/external/v1/keys, DELETE /api/external/v1/keys/:id

Settings and Profile

/dashboard/settings, /dashboard/profile

covered

Resources: settings, connections

Workspace settings and password updates are documented. Profile identity details come from the authenticated Supabase session rather than an external API-key route.

Documented routes: GET /api/external/v1/settings, PUT /api/external/v1/settings, PUT /api/external/v1/settings/password, GET /api/external/v1/connections

Audit Logs

/dashboard/audit

covered

Resources: audit-logs

External clients can query the audit trail shown in the dashboard.

Documented routes: GET /api/external/v1/audit-logs

Brand Discovery and Scoping

components/providers/BrandProvider

covered

Resources: brands

External callers discover brands and scope requests with x-solo-brand-id or brand_id. Without an explicit brand, API-key routes use the first accessible/default brand. Browser active-brand changes, brand creation/deletion, and schedule migration remain dashboard-only guarded flows.

Documented routes: GET /api/external/v1/brands

Designer Labs

/dashboard/designer-labs/canvaslite, /dashboard/designer-labs/solodesignstudio

internal-only

CanvasLite and SoLoDesignStudio are embedded design-tool UI surfaces, not SoLoSocialStudio external API resources.

Advanced YouTube Automation

/dashboard/connections, /dashboard/posts/new

covered

Resources: youtube

Hosted YouTube publishing only needs connect/upload/basic stats; these routes document optional advanced workspace automation.

Documented routes: GET /api/external/v1/youtube/playlists, POST /api/external/v1/youtube/playlists, POST /api/external/v1/youtube/comments, PATCH /api/external/v1/youtube/videos, DELETE /api/external/v1/youtube/videos, +8 more

AI Video Budget and Usage Visibility

/dashboard/posts/new, /dashboard/media-library

covered

Resources: ai, media-library

External clients can capture visible AI video budget, spend-cap, quota, and generated-video usage before and after a one-generation paid smoke test.

Documented routes: GET /api/external/v1/ai/usage

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 or cancel existing publish jobs.

brands:read

List accessible brands and their content counts.

platforms:read

Read platform availability and config status.

connections:read

Read connected account metadata.

connections:write

Create, select, and 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

GET/api/external/v1/ai/usage

external-api-key

ai:generate

Read AI video usage, budget, quota, credits, and spend-cap visibility for paid smoke-test controls without starting generation.

App parity: /api/ai/usage

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

brands

GET/api/external/v1/brands

external-api-key

brands:read

List accessible brands with content counts. Use a valid x-solo-brand-id or ?brand_id=... on brand-scoped routes to target a specific brand; otherwise API-key routes use the first accessible/default brand.

App parity: /api/brands

connections

GET/api/external/v1/connections

external-api-key

connections:read

List connected accounts.

App parity: /api/connections

GET/api/external/v1/connections/meta-pages

external-api-key

connections:read

List Facebook Pages or Instagram business accounts available through the connected Meta user token for the resolved brand.

App parity: /api/connections/meta-pages

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

PATCH/api/external/v1/connections/:platform

external-api-key

connections:write

Select a specific Facebook Page or Instagram business account from the connected Meta account for the resolved brand.

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

PATCH/api/external/v1/content-folders

external-api-key

posts:write or media-library:write

Rename or move a post or media folder. The required scope depends on the body scope.

App parity: /api/content-folders

DELETE/api/external/v1/content-folders

external-api-key

posts:write or media-library:write

Delete an empty post or media folder. The required scope depends on the body scope.

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

DELETE/api/external/v1/media-library

external-api-key

media-library:write

Delete one or more media library items by id and remove their stored assets when present.

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. Response includes publish_job when queue creation succeeds; queue insertion failures return 500 instead of silently leaving the post Scheduled.

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 for jobs whose post row still exists. Optional query params: tag, post_id. Results are newest-first and capped at 200 rows; use post_id to verify a specific publish-now queue entry. Use missing-content to diagnose orphan queued/running jobs.

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 or missing post records.

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/:id

external-api-key

schedule:write

Cancel a queued or running publish job; orphan jobs whose post row no longer exists are deleted and return orphaned_post=true, deleted=true.

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