Application API

Socialize

Clear API and contract surface for Socialize, grouped under the application instead of split across generic reference sections.

OpenAPI-backed srv_1R2xJCdwS7Aq

Documentation Map

Authority

Service IDs:

srv_1R2xJCdwS7Aq

Repos: PlatformApplications/TopoloSocialize

Hosts:

https://socialize.topolo.app

Dependencies: topolo-auth, topolo-nexus, topolo-one, applications-packages

Depends on Topolo Auth: yes

Contract Source

Type: generated OpenAPI

Source: PlatformApplications/TopoloSocialize/packages/worker/openapi.yaml

Source exists: yes

The worker remains the primary API owner, and the authenticated web workspace renders through `TopoloAppShell`, inheriting shared Improve Topolo and TopoloNotify chrome while keeping brand workflows Socialize-owned. The browser app-switcher lane now reads Auth-owned catalog data through same-origin /api/auth/* on the Socialize host. `POST /api/brands/:brandId/transfer-organization` moves an existing brand to another accessible Topolo Auth organization by updating `brands.topolo_org_id` without changing the brand ID or content records. `PUT /api/posts/:id` supports reverting scheduled posts to drafts by clearing the schedule and returning draft state before the browser reports success, and now preserves explicit Facebook Page or Group, LinkedIn organization, and Instagram account target metadata during browser edits. `GET /api/integrations` now returns eligible Facebook Groups alongside Pages from the stored connection metadata and reports whether each provider is production-ready, sandbox-only, setup-required, or still planned. `POST /api/integrations/{platform}/connect` now rejects non-connectable providers up front instead of generating placeholder OAuth redirects. Nexus now supplies the org-wide image-generation default and allowed image-model catalog for Socialize image tools, and inline model overrides remain request-scoped and permission-gated instead of mutating the stored org setting. The worker now also exposes authenticated `GET /api/widget` for TopoloOne live workspace. Embedded password-login success completes through Socialize app navigation after shared Auth token persistence, login controls stay interactive while background auth bootstrap runs, and same-tab session-storage access-token restore preserves normal browser refreshes before cookie refresh completes. Socialize mobile resolves `topolo_auth_flutter` from the canonical Auth repo git package path and does not preload Auth identity from SharedPreferences.

API key scopes in Auth catalog: 9

Auth Requirements

No global OpenAPI security scheme is declared.

  • accounts.read
  • accounts.write
  • analytics.read
  • api_keys.write
  • calendar.read
  • calendar.write
  • dashboard.read
  • posts.read
  • posts.write

Runtime and Deployment

Wrangler surfaces: PlatformApplications/TopoloSocialize/apps/web/wrangler.toml, PlatformApplications/TopoloSocialize/packages/scheduler/wrangler.toml, PlatformApplications/TopoloSocialize/wrangler.toml

Environment variables: API_URL, APP_URL, ENVIRONMENT, ORG_SLUG, SERVICE_ID, TIKTOK_USE_SANDBOX, TOPOLO_AUTH_DOMAIN

Routes: workers.dev or Pages-only delivery

Observability enabled: yes

Servers

  • https://socialize-prod-api.topolo.workers.dev Production API
  • http://localhost:8787 Local development

Operations

Health
  • GET /health Comprehensive health check Responses: 200, 503
  • GET /healthz Liveness probe Responses: 200
  • GET /readyz Readiness probe Responses: 200, 503
Posts
  • GET /api/posts List posts Auth: BearerAuth (http) Responses: 200, 401
  • POST /api/posts Create a post Auth: BearerAuth (http) Responses: 201, 400, 401
  • GET /api/posts/{postId} Get a post Auth: BearerAuth (http) Responses: 200, 404
  • PUT /api/posts/{postId} Update a post Auth: BearerAuth (http) Responses: 200, 404
  • DELETE /api/posts/{postId} Delete a post Auth: BearerAuth (http) Responses: 204, 404
Content Ops
  • GET /api/content-ops/queue List machine-readable content queue items Auth: BearerAuth (http), ApiKeyAuth (apiKey) Responses: 200, 401
  • GET /api/content-ops/daily Get deterministic daily content rollups Auth: BearerAuth (http), ApiKeyAuth (apiKey) Responses: 200, 401
  • GET /api/content-ops/events List content operations audit events Auth: BearerAuth (http), ApiKeyAuth (apiKey) Responses: 200, 401
  • GET /api/content-ops/deck List the freshness-ranked approval deck Auth: BearerAuth (http), ApiKeyAuth (apiKey) Responses: 200, 401
  • GET /api/content-ops/items/{contentId} Get a content item with full machine-readable detail Auth: BearerAuth (http), ApiKeyAuth (apiKey) Responses: 200, 404
  • PATCH /api/content-ops/items/{contentId} Edit draft content safely Auth: BearerAuth (http), ApiKeyAuth (apiKey) Responses: 200
  • POST /api/content-ops/items/{contentId}/approve Approve a suggestion draft Auth: BearerAuth (http), ApiKeyAuth (apiKey) Responses: 200
  • POST /api/content-ops/items/{contentId}/reject Reject a suggestion draft Auth: BearerAuth (http), ApiKeyAuth (apiKey) Responses: 200
  • POST /api/content-ops/items/{contentId}/reschedule Reschedule a queued or failed post Auth: BearerAuth (http), ApiKeyAuth (apiKey) Responses: 200
  • POST /api/content-ops/items/{contentId}/retry Retry a failed publish Auth: BearerAuth (http), ApiKeyAuth (apiKey) Responses: 200
Media
  • GET /api/media List media files Auth: BearerAuth (http) Responses: 200
  • POST /api/media/upload Get upload URL Auth: BearerAuth (http) Responses: 200
AI
  • POST /api/ai/generate-image Generate AI image Auth: BearerAuth (http) Responses: 200, 429
  • GET /api/trends List normalized trend or shared-seed items for a brand Auth: BearerAuth (http), ApiKeyAuth (apiKey) Responses: 200
Content Strategy
  • GET /api/seeds List shared seeds for a brand Auth: BearerAuth (http), ApiKeyAuth (apiKey) Responses: 200
  • POST /api/seeds/share Save a shared source item as a reusable seed Auth: BearerAuth (http), ApiKeyAuth (apiKey) Responses: 201
  • POST /api/content-strategy/suggestions/generate-from-trends Generate platform-specific suggestions from supplied trend or seed items Auth: BearerAuth (http), ApiKeyAuth (apiKey) Responses: 201
Brands
  • GET /api/brands/{brandId}/publishing-readiness Report machine-readable publishing readiness by platform Auth: BearerAuth (http), ApiKeyAuth (apiKey) Responses: 200
  • GET /api/brands List user's brands Auth: BearerAuth (http) Responses: 200
  • POST /api/brands Create a brand Auth: BearerAuth (http) Responses: 201
  • POST /api/brands/{brandId}/transfer-organization Transfer brand ownership to another organization Auth: BearerAuth (http) Responses: 200, 400, 401, 404
Integrations
  • POST /api/integrations/{platform}/connect Start OAuth flow Auth: BearerAuth (http) Responses: 200, 409
  • GET /api/integrations List connected integrations Auth: BearerAuth (http) Responses: 200

Copyable cURL

GET /health

Comprehensive health check

curl -X GET 'https://socialize-prod-api.topolo.workers.dev/health' \
  -H 'Accept: application/json'
GET /healthz

Liveness probe

curl -X GET 'https://socialize-prod-api.topolo.workers.dev/healthz' \
  -H 'Accept: application/json'
GET /readyz

Readiness probe

curl -X GET 'https://socialize-prod-api.topolo.workers.dev/readyz' \
  -H 'Accept: application/json'
GET /api/posts

List posts

curl -X GET 'https://socialize-prod-api.topolo.workers.dev/api/posts' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>'
POST /api/posts

Create a post

curl -X POST 'https://socialize-prod-api.topolo.workers.dev/api/posts' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{}'
GET /api/posts/{postId}

Get a post

curl -X GET 'https://socialize-prod-api.topolo.workers.dev/api/posts/{postId}' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>'
PUT /api/posts/{postId}

Update a post

curl -X PUT 'https://socialize-prod-api.topolo.workers.dev/api/posts/{postId}' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{}'
DELETE /api/posts/{postId}

Delete a post

curl -X DELETE 'https://socialize-prod-api.topolo.workers.dev/api/posts/{postId}' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>'
GET /api/content-ops/queue

List machine-readable content queue items

curl -X GET 'https://socialize-prod-api.topolo.workers.dev/api/content-ops/queue' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>'
GET /api/content-ops/daily

Get deterministic daily content rollups

curl -X GET 'https://socialize-prod-api.topolo.workers.dev/api/content-ops/daily' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>'
GET /api/content-ops/events

List content operations audit events

curl -X GET 'https://socialize-prod-api.topolo.workers.dev/api/content-ops/events' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>'
GET /api/content-ops/deck

List the freshness-ranked approval deck

curl -X GET 'https://socialize-prod-api.topolo.workers.dev/api/content-ops/deck' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>'