> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trypost.it/llms.txt
> Use this file to discover all available pages before exploring further.

# Create post

> Create a new draft post targeting one or more social accounts. Returns the created post with status 201.

Creates a `draft`. To schedule or publish, follow up with [`PUT /posts/{post}`](/api-reference/endpoint/update-post) using `status=scheduled` or `status=publishing`.

<Note>
  Per-platform settings go in `platforms[].meta` and are accepted here on create. A few are **required to publish** — Pinterest `board_id`, TikTok `privacy_level` (string enum values like `"PUBLIC_TO_EVERYONE"`), Discord `channel_id` — but they're only enforced when you move the post to `scheduled`/`publishing`, not on this draft create. Full key list, limits, and examples: [`PUT /posts/{post}` → Per-platform meta](/api-reference/endpoint/update-post#per-platform-meta).
</Note>

## Request

<ParamField body="platforms" type="array" required>
  At least one platform entry (`min:1`). Each entry pins this post to a connected social account and a `content_type`.

  <Expandable>
    <ParamField body="social_account_id" type="string" required>
      UUID of an active social account in the current workspace. Inactive or external accounts are rejected.
    </ParamField>

    <ParamField body="content_type" type="string" required>
      Format for this platform — must match the social account's platform. Discover the live catalog with [`GET /content-types`](/api-reference/endpoint/list-content-types).

      Allowed values today: `linkedin_post`, `linkedin_page_post`, `x_post`, `facebook_post`, `facebook_reel`, `facebook_story`, `instagram_feed`, `instagram_reel`, `instagram_story`, `tiktok_video`, `tiktok_photo`, `youtube_short`, `threads_post`, `pinterest_pin`, `pinterest_video_pin`, `pinterest_carousel`, `bluesky_post`, `mastodon_post`, `telegram_post`, `discord_message`.

      There is **no** `linkedin_carousel` / `instagram_carousel` — use `linkedin_post` + PDF for LinkedIn documents, and `instagram_feed` with multiple images for Instagram carousels.
    </ParamField>

    <ParamField body="meta" type="object">
      Optional per-platform settings. Only documented keys are stored; unknown keys are dropped.

      Summary (see [`PUT /posts/{post}`](/api-reference/endpoint/update-post#per-platform-meta) for the full contract):

      * **Instagram / Facebook** — `aspect_ratio` (`"1:1"` | `"4:5"` | `"16:9"` | `"original"`)
      * **LinkedIn / LinkedIn Page** — `document_title` (max 300; PDF document posts)
      * **TikTok** — `privacy_level` (**required to publish**; exact strings `"PUBLIC_TO_EVERYONE"`, `"MUTUAL_FOLLOW_FRIENDS"`, `"FOLLOWER_OF_CREATOR"`, `"SELF_ONLY"`) plus booleans `allow_comments`, `allow_duet`, `allow_stitch`, `auto_add_music`, `is_aigc`, `disclose`, `brand_content_toggle`, `brand_organic_toggle`
      * **Pinterest** — `board_id` (**required to publish** — [`GET /social-accounts/{account}/boards`](/api-reference/endpoint/list-pinterest-boards)), `title` (max 100), `link` (http/https URL, max 2048). Pin description = post `content`.
      * **Discord** — `channel_id` (**required to publish** — [`GET /social-accounts/{account}/channels`](/api-reference/endpoint/list-discord-channels)), `channel_name`, `mentions` (`[{token, label}]`), `embeds` (up to 10)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="content" type="string">
  The post body shared across all platforms. Up to **10 000** characters at the API level (per-platform hard caps are enforced separately — see [`GET /content-types`](/api-reference/endpoint/list-content-types)). Defaults to empty. For Pinterest, this is the pin description.
</ParamField>

<ParamField body="media" type="array">
  Optional media to attach on create. Each item must include a public `url` — the API downloads and hosts it.

  <Expandable>
    <ParamField body="url" type="string" required>
      Public `http`/`https` URL of the file (max 2048).
    </ParamField>

    <ParamField body="meta" type="object">
      Optional. `meta.alt_text` (string, max **2000**) for image accessibility. Not the same as `platforms[].meta`.
    </ParamField>

    <ParamField body="id" type="string">
      Optional — usually omitted on create (assigned after host).
    </ParamField>

    <ParamField body="path" type="string">
      Optional — usually omitted on create.
    </ParamField>

    <ParamField body="type" type="string">
      Optional hint: `image`, `video`, or `document`.
    </ParamField>

    <ParamField body="mime_type" type="string">
      Optional MIME hint.
    </ParamField>

    <ParamField body="original_filename" type="string">
      Optional display filename (max 500).
    </ParamField>

    <ParamField body="size" type="integer">
      Optional size in bytes.
    </ParamField>

    <ParamField body="source" type="string">
      Optional: `ai`, `unsplash`, or `giphy`.
    </ParamField>

    <ParamField body="source_meta" type="object">
      Optional opaque source metadata.
    </ParamField>
  </Expandable>

  Prefer dedicated endpoints when practical: [`POST /posts/{post}/media`](/api-reference/endpoint/upload-media) (file), [`POST /posts/{post}/media/from-url`](/api-reference/endpoint/attach-media-from-url), or [`POST /posts/{post}/media/from-asset`](/api-reference/endpoint/attach-existing-asset) to reuse a library item.
</ParamField>

<ParamField body="scheduled_at" type="string">
  ISO 8601 datetime in the future (e.g. `2026-05-10T15:30:00Z`). Stored on the draft so a follow-up `PUT` with `status=scheduled` doesn't have to repeat it. **If omitted, the draft has `scheduled_at: null`** (no default time).
</ParamField>

<ParamField body="label_ids" type="array">
  Workspace label UUIDs to attach. Must belong to the same workspace as the API key.
</ParamField>

## Response

Returns `201` with the created post (including `platforms[].meta`). Response shape matches [`GET /posts/{post}`](/api-reference/endpoint/get-post). Labels may not be eager-loaded on create — call `GET` if you need them immediately after setting `label_ids`.

<RequestExample>
  ```bash theme={null}
  curl -X POST https://app.trypost.it/api/posts \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "content": "New pin from the TryPost API",
      "platforms": [
        {
          "social_account_id": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
          "content_type": "pinterest_pin",
          "meta": {
            "board_id": "1234567890123456789",
            "title": "Summer lookbook",
            "link": "https://example.com/shop/summer"
          }
        }
      ],
      "scheduled_at": "2026-05-10T15:30:00Z"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "content": "New pin from the TryPost API",
    "media": [],
    "status": "draft",
    "scheduled_at": "2026-05-10 15:30:00",
    "published_at": null,
    "platforms": [
      {
        "id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
        "platform": "pinterest",
        "content_type": "pinterest_pin",
        "meta": {
          "board_id": "1234567890123456789",
          "title": "Summer lookbook",
          "link": "https://example.com/shop/summer"
        },
        "status": "pending",
        "enabled": true,
        "platform_url": null,
        "published_at": null,
        "error_message": null,
        "display_name": "Acme Brand",
        "display_username": "acme",
        "display_avatar": "https://i.pinimg.com/.../avatar.jpg",
        "social_account": {
          "id": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
          "platform": "pinterest",
          "display_name": "Acme Brand",
          "username": "acme",
          "is_active": true,
          "status": "connected"
        }
      }
    ],
    "labels": [],
    "created_at": "2025-01-14 09:00:00",
    "updated_at": "2025-01-14 09:00:00"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.