> ## 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.

# Create Social Post

> Publish or schedule a social post.

Publishes immediately or schedules a social post. The returned `post_id` is the ID to use with `GET /social/post/{post_id}`, `GET /social/post/{post_id}/analytics`, `GET /social/post/{post_id}/comments`, `PATCH /social/post/{post_id}`, and `DELETE /social/post/{post_id}`. Use `GET /social/posts` to list posts.

Use `destinations` with `social_connection_id` values from `GET /social/connections` to post to specific accounts, including multiple accounts on the same platform.

## Request

```bash theme={null}
curl -X POST "https://api.mosaic.so/social/post" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "post": "Motion product update",
    "destinations": [
      { "social_connection_id": "62c07212-eeb5-40e2-9902-e478027b8628" },
      { "social_connection_id": "8b59f2d7-53fa-4f47-9850-cb4b78b19a8d" }
    ],
    "media_urls": ["https://cdn.yourdomain.com/media/launch.mp4"],
    "schedule_date": "2026-03-10T16:00:00Z"
  }'
```

## Body Parameters

| Field           | Type          | Required    | Description                                                                                                                                                                             |
| --------------- | ------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `post`          | string        | No          | Post text. Defaults to an empty string.                                                                                                                                                 |
| `platforms`     | array         | Conditional | One or more target platforms (`x`, `linkedin`, `instagram`, `facebook`, `tiktok`, `youtube`). Uses the first active account for each platform. Required when `destinations` is omitted. |
| `destinations`  | array         | Conditional | Explicit target accounts. Each item may be a `social_connection_id` string or an object with `social_connection_id`. Required when `platforms` is omitted.                              |
| `media_urls`    | array         | No          | Public media URLs to attach.                                                                                                                                                            |
| `schedule_date` | string        | No          | ISO timestamp to schedule instead of posting immediately.                                                                                                                               |
| `workspace_id`  | string (uuid) | No          | Workspace to associate with the post. Defaults to the organization's primary workspace.                                                                                                 |

Additional social publishing fields are accepted when supported.

## Scheduling

When `schedule_date` is in the future, Mosaic queues the post and returns a `post_id` you can use right away. The post's aggregate `status` is `scheduled` until the scheduled publish time is reached and publishing completes. Native `platform_post_id` and `post_url` values are `null` while the post is still waiting to publish.

Call `GET /social/post/{post_id}` to check whether the post is still scheduled or has published.

## Scheduled Response

```json theme={null}
{
  "post_id": "2d8ca860-f8e0-4f3f-9f2c-337ead6ed91e",
  "status": "scheduled",
  "publishing_status": null,
  "scheduled_at": "2026-03-10T16:00:00Z",
  "platforms": ["x", "linkedin"],
  "links": [],
  "results": [
    {
      "platform": "x",
      "status": "scheduled",
      "platform_post_id": null,
      "post_url": null,
      "message": null,
      "social_connection_id": "62c07212-eeb5-40e2-9902-e478027b8628"
    },
    {
      "platform": "linkedin",
      "status": "scheduled",
      "platform_post_id": null,
      "post_url": null,
      "message": null,
      "social_connection_id": "8b59f2d7-53fa-4f47-9850-cb4b78b19a8d"
    }
  ],
  "destination_results": {
    "62c07212-eeb5-40e2-9902-e478027b8628": {
      "social_connection_id": "62c07212-eeb5-40e2-9902-e478027b8628",
      "platform": "x",
      "status": "scheduled",
      "platform_post_id": null,
      "post_url": null,
      "message": null
    },
    "8b59f2d7-53fa-4f47-9850-cb4b78b19a8d": {
      "social_connection_id": "8b59f2d7-53fa-4f47-9850-cb4b78b19a8d",
      "platform": "linkedin",
      "status": "scheduled",
      "platform_post_id": null,
      "post_url": null,
      "message": null
    }
  },
  "destinations": [
    {
      "social_connection_id": "62c07212-eeb5-40e2-9902-e478027b8628",
      "platform": "x",
      "account_name": "Motion",
      "account_username": "motion_so"
    },
    {
      "social_connection_id": "8b59f2d7-53fa-4f47-9850-cb4b78b19a8d",
      "platform": "linkedin",
      "account_name": "Motion",
      "account_username": "motion-so"
    }
  ],
  "error": null,
  "publishing_errors": []
}
```

## Response Details

* `post_id` is the Mosaic social post ID. Use it for all post status, analytics, update, and delete calls.
* `status` is Mosaic's aggregate status for the requested destinations.
* `results` contains per-destination publishing outcomes when available.
* `destination_results` is keyed by `social_connection_id` and preserves multiple accounts on the same platform.
* `platform_post_id` is the native post ID from the destination platform. It can be `null` while a scheduled post is still waiting to publish.