Socialize API | Topolo Internal Handbook

Documentation Map

Authority

Service IDs:

srv_1R2xJCdwS7Aq

Repos: Applications/TopoloSocialize

Hosts:

https://socialize.topolo.app

Dependencies: topolo-auth, topolo-one

Depends on Topolo Auth: yes

Contract Source

Type: generated OpenAPI

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

Source exists: yes

API key scopes in Auth catalog: 14

Auth Requirements

No global OpenAPI security scheme is declared.

brands.read (brand:*)
posts.read
posts.write
campaigns.read
campaigns.write
analytics.read
media.read
media.write
suggestions.read
suggestions.write
settings.read
settings.write
integrations.read
integrations.write

Runtime and Deployment

Wrangler surfaces: Applications/TopoloSocialize/packages/scheduler/wrangler.toml, Applications/TopoloSocialize/wrangler.toml

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

Routes: workers.dev or Pages-only delivery

Observability enabled: no explicit signal found

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

POST /api/ai/generate-image Generate AI image Auth: BearerAuth (http) Responses: 200, 429

Brands

GET /api/brands List user's brands Auth: BearerAuth (http) Responses: 200
POST /api/brands Create a brand Auth: BearerAuth (http) Responses: 201

Integrations

GET /api/integrations/{platform}/connect Start OAuth flow Auth: BearerAuth (http) Responses: 302
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/items/{contentId}

Get a content item with full machine-readable detail

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