---
title: "Publish or schedule a post"
method: POST
path: "/social/posts"
tags: ["Social"]
---

# Publish or schedule a post

`POST /social/posts`

## Request

- Base URL: `https://api.rendley.com/v1`
- URL: `https://api.rendley.com/v1/social/posts`
- Auth: API key in header `Authorization`

Posts a video or image to the given connected accounts now, or at scheduled_at. Creates one post per account. If some accounts fail after others went out, the call still succeeds and the failed ones come back with status failed and an error, so retrying never posts twice. media_url can be any public HTTPS link to the file, for example a Rendley export URL: posting now hands the link to Post for Me as is; a scheduled post copies the file first, so the link may expire before the scheduled time. Requires a plan with social publishing.

## Request body

- SocialCreatePostDTO
  - `account_ids` string[], required: Ids from GET /social/accounts.
  - `caption` string: Checked against each target platform's limit, e.g. 280 characters on X.
  - `captions` object: Per-platform caption keyed by platform, e.g. {"x": "..."}; overrides caption for that platform.
  - `media_url` string, required: Public HTTPS link to an mp4/mov video or a jpeg/png/webp/gif image, e.g. an export URL.
  - `platform_options` SocialPlatformOptions
    - `instagram` SocialInstagramOptions
      - `placement` 'reels' | 'timeline' | 'stories': reels (default), timeline (feed) or stories.
      - `share_to_feed` boolean: A reel also shows in the feed, not only in the Reels tab.
    - `tiktok` SocialTiktokOptions
      - `allow_comment` boolean
      - `allow_duet` boolean
      - `allow_stitch` boolean
      - `is_ai_generated` boolean
      - `privacy_status` 'public' | 'private': public (default) or private.
    - `youtube` SocialYoutubeOptions
      - `made_for_kids` boolean
      - `privacy_status` 'public' | 'unlisted' | 'private': public (default), unlisted or private.
      - `tags` string[], required
      - `title` string: Video title; defaults to the caption, so it is required when the caption is longer than 100 characters.
  - `project_id` string: The Rendley project the video comes from, shown with the post in the app.
  - `scheduled_at` string: RFC 3339 time to publish at; omit to publish now.
  - `thumbnail_url` string: Preview image the app shows with the post; not sent to the platforms.
  - `workspace_id` string, required

## Response `200`

OK

- object
  - `data` SocialSocialPostResponse[]: Success data
    - `account_username` string
    - `caption` string
    - `created_at` string
    - `error` string
    - `error_code` string: account_expired, media_rejected or rate_limited when the failure is a known kind.
    - `id` string
    - `metrics` SocialPostMetrics
      - `comments` integer
      - `likes` integer
      - `saves` integer
      - `shares` integer
      - `views` integer
    - `platform` string
    - `platform_options` SocialPlatformOptions
      - `instagram` SocialInstagramOptions
        - `placement` 'reels' | 'timeline' | 'stories': reels (default), timeline (feed) or stories.
        - `share_to_feed` boolean: A reel also shows in the feed, not only in the Reels tab.
      - `tiktok` SocialTiktokOptions
        - `allow_comment` boolean
        - `allow_duet` boolean
        - `allow_stitch` boolean
        - `is_ai_generated` boolean
        - `privacy_status` 'public' | 'private': public (default) or private.
      - `youtube` SocialYoutubeOptions
        - `made_for_kids` boolean
        - `privacy_status` 'public' | 'unlisted' | 'private': public (default), unlisted or private.
        - `tags` string[], required
        - `title` string: Video title; defaults to the caption, so it is required when the caption is longer than 100 characters.
    - `project_id` string
    - `result` object
    - `scheduled_at` string
    - `status` string
    - `thumbnail_url` string
  - `error` HttpResponseAPIError
    - `code` string
    - `fields` HttpResponseFieldError[]
      - `field` string
      - `message` string
    - `message` string
  - `meta` unknown

## Other responses

- `400`: VALIDATION_ERROR (caption over a platform's limit, scheduled_at in the past), INVALID_MEDIA_URL, SOCIAL_POST_REJECTED
- `401`: Unauthorized
- `403`: SUBSCRIPTION_REQUIRED
- `404`: PROJECT_NOT_FOUND, or an account id not connected to the workspace

---

[API](https://skmtc.dev/rendley/apis/rendley-api.md) - [All operations](https://skmtc.dev/rendley/apis/rendley-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rendley/apis/rendley-api/revisions/7eb8713bbf78?raw)