Social API

REST endpoints for the Social module — social posts, provider profiles, engagement metrics.

Endpoints

Method	Path	Purpose
GET	`/api/social/posts`	List posts. Filters: `status`, `platform`, date range.
POST	`/api/social/posts`	Create + immediately publish OR schedule (set `scheduled_at`).
GET/PATCH/DELETE	`/api/social/posts/{id}`	CRUD.
GET	`/api/social/posts/{id}/analytics`	Latest engagement snapshot for one post.
GET	`/api/social/posts/{id}/comments`	Comments synced for one post.
GET	`/api/social/accounts`	List linked social accounts.
POST	`/api/social/accounts/link`	Begin OAuth link flow.
GET	`/api/social/accounts/callback`	OAuth provider redirect lands here.
GET/PATCH/DELETE	`/api/social/accounts/{id}`	CRUD on a linked account.
GET	`/api/social/campaigns`	List campaigns (optional grouping).

Key entity shapes

Social post

{
  "id": "uuid",
  "content": "string",
  "media_urls": ["string"],
  "account_ids": ["uuid"],
  "campaign_id": "uuid?",
  "status": "draft | scheduled | published | failed",
  "scheduled_at": "iso-8601?",
  "published_at": "iso-8601?",
  "metadata": {
    "ayrshare_id": "string?",
    "platform_post_ids": { },
    "platform_post_urls": { }
  }
}

Permissions

Seeded slugs: social.posts.read|create|update|delete, social.analytics.read. Account-linking and engagement actions gate on those overlays plus tenant-admin checks; there are no separate seeded slugs for social.providers.* or social.comments.*.

Events

social.post.scheduled
social.post.published

Other lifecycle changes (failures, deletions, comment ingress) surface in the in-app activity feed but are not emitted as webhook events today.

Webhooks (inbound)

POST /api/webhooks/ayrshare — provider callback on publish status + comments + analytics deltas. Verifies shared secret.

OpenAPI

Full schema at /api/openapi.json.