Skip to main content
POST
/
social
/
post
Create Social Post
curl --request POST \
  --url https://api.example.com/social/post

Documentation Index

Fetch the complete documentation index at: https://docs.mosaic.so/llms.txt

Use this file to discover all available pages before exploring further.

Publishes immediately or schedules a social post and returns a post ID. This endpoint writes a tracking record to scheduled_social_posts_v2 for every request.
  • post_id is the provider post ID returned by Ayrshare.
  • tracking_id is Mosaic’s scheduled_social_posts_v2.id value for the tracked record.

​
Request

curl -X POST "https://api.mosaic.so/social/post" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "post": "New product update 🚀",
    "platforms": ["x", "linkedin"],
    "media_urls": ["https://cdn.yourdomain.com/media/launch.mp4"],
    "schedule_date": "2026-03-10T16:00:00Z"
  }'

​
Body Parameters

FieldTypeRequiredDescription
poststringNoPost text (defaults to empty string).
platformsarrayYesOne or more target platforms (x, linkedin, instagram, facebook, tiktok, youtube).
media_urlsarrayNoPublic media URLs to attach. Mosaic validates URL format; provider/platform validation happens downstream.
schedule_datestringNoISO timestamp to schedule instead of posting immediately.
workspace_idstring (uuid)NoWorkspace to associate with the tracked record. Defaults to the organization’s primary workspace.
Additional provider-specific fields are forwarded to Ayrshare.
  • URLs in post text are forwarded as plain text.
  • media_urls accepts any syntactically valid URL, but the media must be reachable by Ayrshare/platforms at publish time.
  • Expired, private, or blocked media links can cause platform-level posting failures.

​
Response

{
  "post_id": "1c08fd57-f0b0-4d10-bf7a-1df2e03c1a96",
  "status": "success",
  "links": [
    {
      "platform": "x",
      "post_url": "https://x.com/usemosaic_ai/status/123"
    }
  ],
  "results": [
    {
      "platform": "x",
      "status": "success",
      "post_id": "1901625213503277588",
      "post_url": "https://x.com/usemosaic_ai/status/123",
      "message": null
    }
  ],
  "error": null,
  "tracking_id": "2d8ca860-f8e0-4f3f-9f2c-337ead6ed91e",
  "tracked_status": "posted"
}

​
Response Notes

  • status and error come from Ayrshare’s response for this request.
  • results contains provider per-platform outcomes when available.
  • tracking_id and tracked_status come from Mosaic scheduled_social_posts_v2.
  • If posting fails at request time, Mosaic returns an API error payload ({"detail":"..."}).
  • To check downstream platform outcomes later, call GET /social/post/{post_id}.
  • To read the tracked Mosaic record directly, call GET /social/post/track/{tracking_id}.

​
Ayrshare References