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

# Create Post

> Create or schedule a post across one or more connected platforms.

## Connection Profiles

Use `profile_id` to publish from a non-default connection profile. Omit it to use the default profile.

Connection profiles let one Mallary user connect multiple accounts on the same platform. Starter includes 5 total social media accounts, Pro includes 15, and Business includes 100. Use any mix of supported platforms across your profiles. Existing customers keep their current account limits.

## Scheduling

* If you already know the exact UTC or offset time, use `scheduled_at` with an absolute timestamp like `2026-04-06T18:30:00Z`.
* To resolve the post in a specific timezone, use a local `scheduled_at` like `2026-04-06T14:30` plus `scheduled_timezone` with an IANA timezone like `America/New_York`.
* Mallary stores the resolved publish time in UTC and returns the original `scheduled_timezone` on grouped post reads.

## Publish Results

Post creation is asynchronous. The create response returns one Mallary job ID per platform immediately, with `platform_post_id` and `platform_post_url` set to `null` until that platform finishes publishing. After completion, use `GET /api/v1/jobs/{id}` or `GET /api/v1/posts`. These return the platform post ID and the public post URL that the platform exposes.

## Video Thumbnails

Attach a custom thumbnail or cover to a video media item with `thumbnail_url`.

```json theme={null}
{
  "message": "Launch walkthrough",
  "platforms": ["youtube", "facebook", "instagram", "tiktok"],
  "media": [
    {
      "url": "https://files.mallary.ai/uploads/launch-video.mp4",
      "type": "video/mp4",
      "thumbnail_url": "https://files.mallary.ai/uploads/launch-cover.jpg"
    }
  ]
}
```

`thumbnail_url` must be a Mallary-hosted image URL, usually created with `POST /api/v1/upload`. Mallary skips a thumbnail that is unsupported for the platform, wrong for the post type, or rejected by the provider. It then continues to publish the post where possible.

To use a different cover for each platform, put `thumbnail_url` inside that platform's options. For example, use `platform_options.youtube.thumbnail_url` for YouTube and `platform_options.instagram.thumbnail_url` for Instagram. Mallary adds each cover only to that platform's video.

Current thumbnail behavior:

* YouTube regular videos: supported. Use a `jpg`, `jpeg`, or `png` image up to 50 MB. Use 16:9 and at least 640px wide.
* YouTube Shorts: YouTube may accept and store the image but show a video frame instead. Mallary warns you because the YouTube API cannot confirm the cover viewers will see. Use YouTube Studio to add a custom image, or use the YouTube app to choose a frame.
* Facebook feed videos: supported. Mallary accepts `jpg`, `jpeg`, or `png` thumbnail images up to 10 MB and retries without the thumbnail if Meta rejects it.
* Instagram videos/Reels: supported with a Mallary-hosted `cover_url`. Use a cover image that matches the video placement, such as 9:16 for Reels/stories. If Meta rejects a cover variant, Mallary falls back to video creation without the cover.
* TikTok video posts: TikTok currently exposes frame-based cover selection through `video_cover_timestamp_ms`, not arbitrary image thumbnails. If `thumbnail_url` is supplied, Mallary does not send `video_cover_timestamp_ms` and lets TikTok use its default cover behavior.
* TikTok photo posts: `thumbnail_url` can choose the photo cover only when it exactly matches one of the image URLs in `media[]`. Mallary then uses that image index as `photo_cover_index`. Mallary does not upload it as an extra photo.

## Platform-Specific Media Rules

Mallary validates media before it queues a platform job. The public API and the current publishers enforce these media rules.

For a simple guide to each setting, see [Platform Posting Options](https://docs.mallary.ai/api-reference/platform-options.md).

### Facebook

* Feed posts can be text-only, link-only, up to 10 images, or 1 video.
* Facebook does not allow mixing images and video in the same post.
* Feed images accept `jpg`, `jpeg`, `png`, `gif`, and `webp`. Feed video accepts `mp4` and `mov`.
* Facebook stories support 1 image or 1 video.
* Facebook Reels use 1 MP4 or MOV video. The video must be 9:16, at least 540 by 960 pixels, and 3 to 90 seconds long.
* Choose `feed`, `story`, or `reel` with `platform_options.facebook.post_type`.
* For a Reel, set `platform_options.facebook.is_ai_generated` to `true` to disclose AI-generated media. This field accepts only a JSON boolean and requires `post_type: "reel"`.
* `platform_options.facebook.message` sets a Facebook-specific message. Omit it to use the top-level `message`.

### Instagram

* Instagram requires media.
* The validator currently defines:
  feed = 1 image or 1 video,
  story = 1 image or 1 video,
  reel = 1 video,
  carousel = 2 to 10 mixed image/video items.
* Set `platform_options.instagram.is_ai_generated` to `true` to disclose AI-generated media, including Reels. This field accepts only a JSON boolean and works with both Instagram Login and Facebook Login.
* The publisher uses the matching Instagram container flow for `feed`, `story`, `reel`, and `carousel` when selected through `platform_options.instagram.post_type`.
* `platform_options.instagram.message` sets an Instagram-specific caption. Omit it to use the top-level `message`.
* For a Reel, `platform_options.instagram.shareToFeed` defaults to `true`. Set it to `false` to keep the Reel in the Reels tab and off the profile feed.
* To publish a Trial Reel, add `platform_options.instagram.trialParams.graduationStrategy`. Use `MANUAL` to choose later in Instagram, or `SS_PERFORMANCE` to let Instagram share it with followers if it performs well. Do not add `shareToFeed` to a Trial Reel request.
* Set `platform_options.instagram.isPaidPartnership` to `true` to show the Paid partnership label on a feed post, Reel, or carousel.
* Add up to two sponsor usernames or numeric user IDs with `platform_options.instagram.brandedContentSponsors`. Sponsors turn on the Paid partnership label too.
* Paid partnership options do not work with Stories. They require an Instagram account connected through Facebook Login.
* Stories support captions through the main `message` or `platform_options.instagram.message`. To place styled text on the image or video, add it to the media before upload. Stories do not support follow-up comments.
* Instagram image uploads use `jpg`, `jpeg`, or `png`. Video uploads use `mp4` or `mov`.
* Instagram Reels and single feed videos must be 3 seconds to 15 minutes long and no larger than 300 MB. Single feed videos publish as Reels shared to the feed.

### LinkedIn

* LinkedIn supports text-only posts, one image or GIF, or one MP4 video.
* Videos can be up to 1 GB (1,073,741,824 bytes) and 3 seconds to 30 minutes long. Do not mix images and video.
* Upload media to Mallary first. Use the returned `files.mallary.ai` URL or `storageKey`.
* Mallary uploads the video to LinkedIn and waits for processing before it publishes the post.
* LinkedIn image attachments accept `jpg`, `jpeg`, `png`, or `gif`.
* `platform_options.linkedin.message` sets a LinkedIn-specific message. Omit it to use the top-level `message`.

### Threads

* Threads supports four posting shapes:
  `text`,
  `image`,
  `video`,
  and `carousel`.
* Text posts are text-only and cannot include media.
* Image posts support exactly 1 image in `jpg`, `jpeg`, `png`, or `webp`.
* Video posts support exactly 1 video in `mp4` or `mov`.
* Carousel posts support 2 to 20 supported media items total.
* `platform_options.threads.post_type` can be `text`, `image`, `video`, or `carousel`.
* If you omit `platform_options.threads.post_type`, Mallary chooses from the payload:
  no media = `text`,
  one image = `image`,
  one video = `video`,
  multiple supported media items = `carousel`.
* `platform_options.threads.message` sets a Threads-specific message. Omit it to use the top-level `message`.
* Threads currently supports `comments_under_post`.

### YouTube

* YouTube requires exactly one video.
* `regular` video supports one video up to 12 hours and up to 256 GB.
* `shorts` supports one video up to 3 minutes. Use vertical video.
* YouTube posting does not support images.
* `platform_options.youtube.message` sets a YouTube-specific description/default-title source. Omit it to use the top-level `message`.
* `platform_options.youtube.title` sets the YouTube title and takes precedence over the first line of the effective message.
* `platform_options.youtube.tags` adds video tags. Each tag can use up to 100 characters, and YouTube allows 500 characters across the full tag list after counting separators.
* `platform_options.youtube.containsSyntheticMedia` accepts `true` or `false`. Set it to `true` when the video contains realistic AI-generated or altered content that could look real. YouTube may show a disclosure label.
* `platform_options.youtube.playlist_id` adds the new video to an existing playlist owned by the connected YouTube channel. Mallary checks the playlist before upload.

### TikTok

* TikTok video posts support one video file in `mp4`, `mov`, or `webm`.
* TikTok photo posts support up to 35 images in `jpg`, `jpeg`, or `webp`.
* `platform_options.tiktok.post_type` can be `video` or `photo`.
* `platform_options.tiktok.post_mode` can be `DIRECT_POST` or `MEDIA_UPLOAD`.
* TikTok defaults to `DIRECT_POST`, which publishes the post through Mallary.
* Use `MEDIA_UPLOAD` only when you want Mallary to send the upload to the TikTok inbox. The job stays `action_required` until you finish the post in TikTok and attach its final TikTok URL.
* For TikTok video posts, `platform_options.tiktok.source` can be `FILE_UPLOAD` or `PULL_FROM_URL`.
* For TikTok photo posts, TikTok only allows `PULL_FROM_URL`.
* For TikTok `PULL_FROM_URL`, Mallary only accepts media already hosted on the Mallary CDN (`https://files.mallary.ai/...`).
* `platform_options.tiktok.message` sets a TikTok-specific caption/title fallback. Omit it to use the top-level `message`.
* `platform_options.tiktok.title` sets the TikTok title and takes precedence over the effective message where TikTok accepts a title.
* `platform_options.tiktok.description` sets the TikTok photo description.
* Direct-post TikTok options include `privacy_level`, `disable_comment`, `disable_duet`, `disable_stitch`, `video_cover_timestamp_ms`, `auto_add_music`, `brand_content_toggle`, `brand_organic_toggle`, `is_aigc`, and `photo_cover_index` where applicable.
* TikTok posts do not currently support `comments_under_post`.

### Pinterest

* Pinterest requires exactly one image or GIF, or exactly one video.
* Pinterest does not allow mixing image and video in the same Pin.
* Image Pins accept one `jpg`, `jpeg`, `png`, `webp`, or `gif` file up to 32 MB.
* Video Pins accept one `mp4` or `mov` file, 4 seconds to 15 minutes, up to 2 GB.
* A Pinterest board is required. Send `boardId`, or use the board saved with the Pinterest connection.
* `platform_options.pinterest.message` sets a Pinterest-specific description/default title source. Omit it to use the top-level `message`. Pinterest allows 800 characters in a description. Mallary shortens longer descriptions to fit.

### Reddit

* `text` and `link` posts do not upload media through the Mallary API.
* `image` posts require one image or GIF up to 20 MB.
* The current public API path does not support Reddit video upload. To point at externally hosted video, use a link post.
* `subreddit` or `subredditName` is required in platform options.
* `platform_options.reddit.message` sets a Reddit-specific title/text source. Omit it to use the top-level `message`.

### Bluesky

* Bluesky supports a text-only post, up to four images, or one video.
* Images can be `jpg`, `jpeg`, `png`, or `webp`, up to 2 MB each.
* Video must be one `mp4` file, up to 300 MB. Bluesky may apply a daily video limit to an account.
* A Bluesky post can have up to 300 characters.
* `platform_options.bluesky.message` sets a Bluesky-specific message. Omit it to use the top-level `message`.
* `platform_options.bluesky.languages` adds up to three language codes. `langs` is also accepted.
* Add `alt_text` to a media item to describe an image or video for people who use screen readers.
* Bluesky supports up to three `comments_under_post` replies.

### X

* X allows up to 4 images, or 1 video, or 1 GIF.
* X does not allow mixing images and video in the same post.
* GIFs cannot be combined with other attachments.
* X images accept `jpg`, `jpeg`, `png`, `webp`, and `gif`. Video accepts `mp4` or `mov`.
* X video limits depend on the connected X account. Standard accounts can use videos up to 20 minutes and 8 GB. Eligible Premium or verified accounts can use videos up to 125 minutes and 16 GB. Mallary checks the connected account before accepting a video above the standard limits.
* Mallary's current upload endpoint accepts files up to 5 GB. This upload limit still applies even when X allows a larger file for the connected account.
* `platform_options.x.message` or `platform_options.twitter.message` sets an X-specific message. Omit it to use the top-level `message`.
* Set `platform_options.x.made_with_ai` to `true` to disclose that the main post was made with AI. `platform_options.twitter.made_with_ai` also works. This field accepts only a JSON boolean and does not label first replies.


## OpenAPI

````yaml POST /api/v1/post
openapi: 3.0.3
info:
  title: Mallary API
  version: 1.6.0
  description: >
    Public API for multi-platform publishing, analytics, media upload, and
    webhooks.


    Authentication:

    - Use header `Authorization: Bearer {api_key}`.

    - API key identity is authoritative. Do not use `user_id` to identify a
    caller.


    Connection profiles:

    - Omit `profile_id` to use the authenticated user's default profile.

    - Send the profile's random public `profile_id` when you want to publish,
    list posts, read post analytics or audience counts, list platforms, update
    settings, or disconnect a platform for a non-default profile.

    - Use `GET /api/v1/profiles` to list profile IDs.

    - Total social media accounts: Starter 5 ($15/month), Pro 15 ($29/month),
    Business 100 ($95/month). Posts are unlimited. Scheduling, analytics, and AI
    auto-replies are included. X publishing and comments use credits at cost;
    analytics and account lookups use no credits. Existing customers keep their
    current terms; use the authenticated workspace limits.


    Rate limits (per user, per minute) depend on subscription plan:

    - plan_id 1: 75 req/min

    - plan_id 2: 150 req/min

    - plan_id 3: 750 req/min

    - plan_id 4: 1500 req/min
servers:
  - url: https://mallary.ai
    description: Production
security:
  - bearerAuth: []
externalDocs:
  description: Full product docs
  url: https://docs.mallary.ai/
paths:
  /api/v1/post:
    post:
      summary: Create or schedule a post across platforms
      description: >-
        Enqueues one job per selected platform and returns job IDs plus
        `batch_id`. Platform post IDs and URLs are `null` in the queued response
        until each platform finishes publishing; read `GET /api/v1/jobs/{id}` or
        `GET /api/v1/posts` for populated `platform_post_id` and
        `platform_post_url` values after completion.
      operationId: createPost
      parameters:
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
          description: Optional idempotency key to prevent duplicate submissions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePostRequest'
      responses:
        '200':
          description: Jobs enqueued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePostResponse'
        '400':
          description: >-
            Validation error (platform/media constraints, unsupported platform,
            etc.)
        '401':
          description: Missing or invalid API key
        '402':
          description: Posting limit reached for current plan
        '403':
          description: >-
            Feature not available on current plan, or supplied `user_id` does
            not match API key owner
        '429':
          description: Rate limit exceeded
components:
  schemas:
    CreatePostRequest:
      type: object
      required:
        - message
        - platforms
      properties:
        message:
          type: string
          minLength: 1
        platforms:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Platform'
        profile_id:
          $ref: '#/components/schemas/ProfileId'
          description: Connection profile to publish from. Omit to use the default profile.
        media:
          type: array
          description: Media URLs obtained from using the /api/v1/upload endpoint.
          items:
            $ref: '#/components/schemas/MediaItem'
        comments_under_post:
          type: array
          maxItems: 3
          items:
            type: string
          description: >-
            Up to 3 follow-up comments/replies under the main post when
            supported by the target platform/format.
        scheduled_at:
          type: string
          description: >-
            Optional scheduled publish timestamp. Send an absolute timestamp
            like `2026-04-06T18:30:00Z`, or send a local datetime like
            `2026-04-06T14:30` together with `scheduled_timezone`.
        scheduled_timezone:
          type: string
          description: >-
            Optional IANA timezone such as `America/New_York`. When provided
            with a local `scheduled_at` that omits an offset, Mallary resolves
            the wall-clock time in this timezone and stores the resulting UTC
            publish time.
        auto_reply_enabled:
          type: boolean
          description: Optional per-post override for AI auto-replies.
        platform_options:
          $ref: '#/components/schemas/PlatformOptions'
          description: Optional per-platform overrides.
        webhook_url:
          type: string
          format: uri
          description: Optional callback URL for completion notifications.
    CreatePostResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - queued
        batch_id:
          type: string
        profile_id:
          type: string
          pattern: ^[A-Za-z0-9]{6,32}$
          nullable: true
        jobs:
          type: array
          items:
            type: object
            properties:
              platform:
                $ref: '#/components/schemas/Platform'
              jobId:
                type: string
              platform_post_id:
                type: string
                nullable: true
                description: >-
                  Platform-returned post ID. `null` until the queued job
                  publishes successfully.
              platform_post_url:
                type: string
                nullable: true
                description: >-
                  Public platform post URL when available. `null` until the
                  queued job publishes successfully or when the platform does
                  not expose a URL.
        warnings:
          type: array
          description: >-
            Non-blocking warnings about provider behavior. A queued post may
            still publish.
          items:
            type: object
            properties:
              platform:
                $ref: '#/components/schemas/Platform'
              code:
                type: string
              severity:
                type: string
                enum:
                  - warning
              message:
                type: string
    Platform:
      type: string
      description: Supported publishing platform identifier.
      enum:
        - twitter
        - x
        - facebook
        - instagram
        - linkedin
        - youtube
        - tiktok
        - pinterest
        - reddit
        - threads
        - bluesky
    ProfileId:
      type: string
      pattern: ^[A-Za-z0-9]{6,32}$
      example: AbC123xYz90
      description: Random public connection profile ID returned by `GET /api/v1/profiles`.
    MediaItem:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: Media URL (`mediaUrl` must be obtained from `/api/v1/upload`).
        type:
          type: string
          description: Optional MIME type hint.
        thumbnail_url:
          type: string
          format: uri
          description: >-
            Optional Mallary-hosted image URL to use as the custom thumbnail or
            cover for a video post when supported by the target platform.
        alt_text:
          type: string
          maxLength: 2000
          description: >-
            Optional media description for accessibility. Bluesky adds it to the
            matching image or video.
    PlatformOptions:
      type: object
      description: Per-platform options keyed by platform id.
      additionalProperties: true
      properties:
        facebook:
          type: object
          properties:
            is_ai_generated:
              type: boolean
              description: >-
                For Facebook Reels only. Set true to disclose AI-generated media
                at publish time. Accepts true or false; omitted by default.
            message:
              type: string
              description: >-
                Facebook-specific message/caption. Defaults to the top-level
                `message`.
            post_type:
              type: string
              enum:
                - feed
                - story
                - reel
              default: feed
              description: >-
                Defaults to `feed` when omitted. `story` publishes one
                image/video as a Facebook Story without caption/follow-up
                comments. `reel` publishes one 9:16 MP4/MOV video that is 3 to
                90 seconds long.
            link:
              type: string
              format: uri
              description: Optional link for a feed post without media.
            pageId:
              type: string
              description: Optional advanced override for a connected Facebook Page.
            title:
              type: string
              maxLength: 255
              description: Optional title for a Facebook Reel.
        instagram:
          type: object
          properties:
            is_ai_generated:
              type: boolean
              description: >-
                Set true to disclose AI-generated media when creating the
                Instagram post. Accepts true or false; omitted by default.
            message:
              type: string
              description: Instagram-specific caption. Defaults to the top-level `message`.
            post_type:
              type: string
              enum:
                - feed
                - story
                - reel
                - carousel
              default: feed
              description: >-
                Defaults to `feed` when omitted. `story` publishes one
                image/video as an Instagram Story with an optional caption and
                no follow-up comments, `reel` requires one video, and `carousel`
                publishes 2 to 10 image/video items as one carousel post.
            shareToFeed:
              type: boolean
              default: true
              description: >-
                For Reels only. When true, the Reel appears in the profile feed
                and Reels tab. When false, it appears only in the Reels tab.
            trialParams:
              type: object
              description: >-
                For Reels only. Add this object to publish the video as a Trial
                Reel that Instagram shows to non-followers first. Do not use
                `shareToFeed` with a Trial Reel.
              required:
                - graduationStrategy
              additionalProperties: false
              properties:
                graduationStrategy:
                  type: string
                  enum:
                    - MANUAL
                    - SS_PERFORMANCE
                  description: >-
                    Use `MANUAL` to decide later in Instagram, or
                    `SS_PERFORMANCE` to let Instagram share the Reel with
                    followers if it performs well.
            isPaidPartnership:
              type: boolean
              description: >-
                Show Instagram's Paid partnership label. Available for feed
                posts, Reels, and carousels connected through Facebook Login.
                Sponsors also turn this on.
            brandedContentSponsors:
              type: array
              maxItems: 2
              description: >-
                Up to two sponsor Instagram usernames or numeric user IDs. Each
                sponsor must be a public Business or Creator account. Available
                only through Facebook Login and not for Stories.
              items:
                type: string
                pattern: ^@?(?:[A-Za-z0-9._]{1,30}|\d{1,64})$
        threads:
          type: object
          properties:
            message:
              type: string
              description: Threads-specific message. Defaults to the top-level `message`.
            post_type:
              type: string
              enum:
                - text
                - image
                - video
                - carousel
              description: >-
                Defaults dynamically. Mallary uses `text` when no media is
                supplied, `carousel` when more than one supported media item is
                supplied, `video` for a single MP4/MOV item, and `image` for a
                single JPG/JPEG/PNG/WEBP item.
        twitter:
          type: object
          properties:
            made_with_ai:
              type: boolean
              description: >-
                Alias for platform_options.x.made_with_ai. Applies to the main X
                post only. Accepts true or false; omitted by default.
            message:
              type: string
              description: X-specific message. Defaults to the top-level `message`.
        x:
          type: object
          properties:
            made_with_ai:
              type: boolean
              description: >-
                Set true to mark the main X post as made with AI. Does not label
                follow-up replies. Accepts true or false; omitted by default.
            message:
              type: string
              description: X-specific message. Defaults to the top-level `message`.
        linkedin:
          type: object
          properties:
            message:
              type: string
              description: LinkedIn-specific message. Defaults to the top-level `message`.
            author_urn:
              type: string
              description: Optional author URN override.
        tiktok:
          type: object
          properties:
            message:
              type: string
              description: >-
                TikTok-specific message/caption. Defaults to the top-level
                `message`.
            post_type:
              type: string
              enum:
                - video
                - photo
              description: >-
                Defaults dynamically. Mallary picks `photo` when the media list
                contains only images and no videos; otherwise it uses `video`.
            media_type:
              type: string
              enum:
                - PHOTO
              description: >-
                Optional alias for selecting the TikTok photo variant. No
                default; use this only when you want to force photo mode via the
                alias.
            post_mode:
              type: string
              enum:
                - DIRECT_POST
                - MEDIA_UPLOAD
              default: DIRECT_POST
              description: >-
                Defaults to `DIRECT_POST`, which publishes through Mallary. Use
                `MEDIA_UPLOAD` only when you want to send the upload to the
                creator inbox and finish publishing it in TikTok.
            source:
              type: string
              enum:
                - FILE_UPLOAD
                - PULL_FROM_URL
              description: >-
                Defaults by variant. Video posts default to `FILE_UPLOAD`. Photo
                posts always use `PULL_FROM_URL`. Mallary only accepts
                `PULL_FROM_URL` media from its own CDN.
            title:
              type: string
              maxLength: 2200
              description: >-
                TikTok caption/title override. Defaults to `message` (trimmed to
                TikTok's limit). For photo posts, TikTok applies a shorter
                platform limit.
            description:
              type: string
              maxLength: 4000
              description: >-
                TikTok photo description override. No default; omitted unless
                supplied.
            privacy_level:
              type: string
              enum:
                - PUBLIC_TO_EVERYONE
                - MUTUAL_FOLLOW_FRIENDS
                - FOLLOWER_OF_CREATOR
                - SELF_ONLY
              description: >-
                Applies to `DIRECT_POST`. Defaults to the first allowed privacy
                level returned by TikTok creator info, preferring
                `PUBLIC_TO_EVERYONE`, then `MUTUAL_FOLLOW_FRIENDS`, then
                `FOLLOWER_OF_CREATOR`, then `SELF_ONLY`. If TikTok returns the
                private-account-only direct-post restriction, Mallary retries
                once with the most private allowed level.
            disable_comment:
              type: boolean
              description: >-
                Controls whether comments are disabled on the TikTok post.
                Applies to direct posts. When omitted, Mallary falls back to the
                creator's current TikTok comment setting.
            disable_duet:
              type: boolean
              description: >-
                Controls whether other TikTok users can create Duets from the
                video. Applies to direct-post video only. When omitted, Mallary
                falls back to the creator's current TikTok duet setting.
            disable_stitch:
              type: boolean
              description: >-
                Controls whether other TikTok users can create Stitches from the
                video. Applies to direct-post video only. When omitted, Mallary
                falls back to the creator's current TikTok stitch setting.
            video_cover_timestamp_ms:
              type: integer
              minimum: 0
              description: >-
                Millisecond timestamp used to choose the video cover frame for a
                direct-post TikTok video. Omitted unless supplied.
            auto_add_music:
              type: boolean
              description: >-
                For direct-post photo posts, asks TikTok to automatically add
                music to the photo carousel. Omitted unless supplied.
            brand_content_toggle:
              type: boolean
              description: >-
                TikTok branded-content disclosure flag. When true, marks the
                post as branded content. Omitted unless supplied.
            brand_organic_toggle:
              type: boolean
              description: TikTok brand-organic disclosure flag. Omitted unless supplied.
            is_aigc:
              type: boolean
              description: >-
                TikTok AI-generated-content disclosure flag for direct-post
                video. Omitted unless supplied.
            photo_cover_index:
              type: integer
              minimum: 0
              default: 0
              description: >-
                Zero-based index of the image TikTok should use as the photo
                carousel cover. Values beyond the image count are clamped to the
                last image. Defaults to `0` when omitted.
        youtube:
          type: object
          properties:
            message:
              type: string
              description: >-
                YouTube-specific description/default-title source. Defaults to
                the top-level `message`.
            post_type:
              type: string
              enum:
                - regular
                - shorts
              description: >-
                Defaults dynamically. Mallary uses `shorts` when the video is
                short-form (<= 180s) and vertical, or when dimensions are
                unavailable for a short candidate; otherwise it uses `regular`.
            title:
              type: string
              maxLength: 100
              description: >-
                Defaults to the first non-empty value of
                `platform_options.youtube.title`, the first line of `message`,
                or `Untitled Video`.
            tags:
              type: array
              description: >-
                Optional video tags. Each tag can use up to 100 characters. The
                complete tag list can use up to 500 characters after YouTube
                counts commas and quote characters around tags with spaces.
                Exact duplicates are removed before upload.
              items:
                type: string
                minLength: 1
                maxLength: 100
                pattern: ^[^<>]*$
            visibility:
              type: string
              enum:
                - public
                - unlisted
                - private
              default: public
              description: Defaults to `public`.
            categoryId:
              type: string
              default: '22'
              description: Defaults to YouTube category id `22`.
            madeForKids:
              type: boolean
              default: false
              description: Defaults to `false`.
            containsSyntheticMedia:
              type: boolean
              description: >-
                Optional AI-content disclosure. Set to `true` when the video
                contains realistic AI-generated or altered content that could be
                mistaken for real people, places, or events. YouTube may show a
                disclosure label. Omitted unless supplied.
            playlist_id:
              type: string
              pattern: ^[A-Za-z0-9_-]{2,150}$
              description: >-
                Existing playlist owned by the connected YouTube channel.
                Mallary checks access before upload, then adds the new video to
                this playlist.
        pinterest:
          type: object
          properties:
            message:
              type: string
              description: >-
                Pinterest-specific description/default title source. Defaults to
                the top-level `message`. Mallary shortens descriptions longer
                than Pinterest's 800-character limit.
            post_type:
              type: string
              enum:
                - image
                - video
              description: >-
                Defaults dynamically. Mallary uses `video` when the media list
                contains a video; otherwise it uses `image`.
            title:
              type: string
              maxLength: 100
            boardId:
              type: string
              description: >-
                Board to post into. Defaults to the connected Pinterest board id
                from the saved token when omitted.
            link:
              type: string
              format: uri
            alt_text:
              type: string
              description: Short image description for people who use screen readers.
        reddit:
          type: object
          properties:
            message:
              type: string
              description: >-
                Reddit-specific title/text source. Defaults to the top-level
                `message`.
            post_type:
              type: string
              enum:
                - text
                - link
                - image
              description: >-
                Defaults dynamically. Mallary uses `image` when the media list
                contains an image; otherwise it uses `text`.
            subreddit:
              type: string
              description: Community that receives the post.
            subredditName:
              type: string
              description: Alias for `subreddit`.
        bluesky:
          type: object
          properties:
            message:
              type: string
              maxLength: 300
              description: Bluesky-specific message. Defaults to the top-level `message`.
            languages:
              type: array
              maxItems: 3
              description: Optional BCP 47 language codes for the post.
              items:
                type: string
            langs:
              type: array
              maxItems: 3
              description: Alias for `languages`.
              items:
                type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Use `Authorization: Bearer {api_key}`'

````

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