{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/postzen-dev/json-schema/postzen-dev-create-post-response-schema.json",
  "title": "CreatePostResponse",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/postzen-dev-posts-api-openapi.yml#/components/schemas/CreatePostResponse",
  "type": "object",
  "required": [
    "post",
    "message"
  ],
  "properties": {
    "post": {
      "$ref": "#/$defs/ApiPost"
    },
    "message": {
      "type": "string",
      "enum": [
        "Post published successfully",
        "Post scheduled successfully",
        "Draft created successfully"
      ]
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Non-fatal notes about settings that were accepted but not applied. Each entry is prefixed with the target account's display name, for example `Jane Doe: LinkedIn first comments are not available yet; this post publishes without the comment.` when a LinkedIn target set `firstComment`. Present only when non-empty."
    },
    "usage": {
      "type": "object",
      "description": "The plan's monthly post usage after this post, counting it. Present only for plans with a monthly post limit (Free) and only for non-draft posts. Use it to warn before the limit; at the limit, creates return 402 `freePostLimitExceeded`.",
      "required": [
        "postsUsed",
        "postLimit",
        "periodEndsAt",
        "upgradeUrl"
      ],
      "properties": {
        "postsUsed": {
          "type": "number",
          "description": "Platform-posts counted in the current UTC month, including this one."
        },
        "postLimit": {
          "type": "number",
          "description": "The plan's monthly platform-post allowance."
        },
        "periodEndsAt": {
          "type": "string",
          "format": "date-time",
          "description": "When the allowance resets: the start of the next UTC month."
        },
        "upgradeUrl": {
          "type": "string",
          "format": "uri",
          "description": "Dashboard billing page, where the user can move to a plan with unlimited posts."
        }
      }
    }
  },
  "$defs": {
    "ApiPost": {
      "type": "object",
      "required": [
        "_id",
        "title",
        "content",
        "status",
        "scheduledFor",
        "timezone",
        "platforms",
        "mediaItems"
      ],
      "properties": {
        "_id": {
          "type": "string"
        },
        "title": {
          "type": [
            "string",
            "null"
          ]
        },
        "content": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "scheduledFor": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "queueId": {
          "type": [
            "string",
            "null"
          ],
          "description": "Queue that placed this post, or null when the post was not queued."
        },
        "timezone": {
          "type": "string"
        },
        "platforms": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ApiPostPlatformResult"
          }
        },
        "mediaItems": {
          "type": "array",
          "description": "Attached media in stored order, with resolved hosted URLs and optional titles (alt text). Always present; empty when there is no available media.",
          "items": {
            "type": "object",
            "required": [
              "url"
            ],
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              },
              "title": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "ApiPostAccount": {
      "type": "object",
      "required": [
        "_id",
        "platform",
        "username",
        "displayName",
        "isActive"
      ],
      "properties": {
        "_id": {
          "type": "string"
        },
        "platform": {
          "$ref": "#/$defs/PublicPlatformInput"
        },
        "username": {
          "type": "string"
        },
        "displayName": {
          "type": "string"
        },
        "isActive": {
          "type": "boolean"
        }
      }
    },
    "ApiPostPlatformResult": {
      "type": "object",
      "required": [
        "platform",
        "accountId",
        "status"
      ],
      "properties": {
        "platform": {
          "$ref": "#/$defs/PublicPlatformInput"
        },
        "accountId": {
          "$ref": "#/$defs/ApiPostAccount"
        },
        "status": {
          "type": "string",
          "enum": [
            "draft",
            "scheduled",
            "pending",
            "publishing",
            "published",
            "failed",
            "canceled"
          ]
        },
        "platformPostId": {
          "type": "string",
          "description": "The platform's own id for the published post. Present as soon as this target is published, so it can be used right away with the inbox and analytics endpoints. For a thread, this is the root post's id. TikTok is the exception: the id and platformPostUrl appear only once TikTok makes the post public, usually within a minute; a draft gets them when the creator posts it, and a photo post gets an id but no URL."
        },
        "platformPostIds": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "X and Threads thread targets only: the platform id of every post in the thread, root first."
        },
        "platformPostUrl": {
          "type": "string",
          "format": "uri"
        },
        "error": {
          "type": "string"
        },
        "platformError": {
          "type": "object",
          "description": "The platform's own error envelope for this failure, present only when the platform returned one (today: Instagram, Facebook, and Threads). Fields the platform did not send are absent. When PostZen stops retrying (`error` begins with \"Publishing failed after too many attempts\"), this is the last attempt's envelope.",
          "properties": {
            "code": {
              "type": "integer",
              "description": "The platform's error code, for example Meta's `36003`."
            },
            "subcode": {
              "type": "integer",
              "description": "The platform's error subcode, for example Meta's `2207009`."
            },
            "fbtraceId": {
              "type": "string",
              "description": "Meta's trace id for the failed call. Quote it to Meta support; Meta expires it after a short time."
            },
            "type": {
              "type": "string",
              "description": "The platform's error type, for example `OAuthException`."
            }
          }
        },
        "customContent": {
          "type": "string",
          "description": "The per-platform content override this target was created with, if any."
        },
        "settings": {
          "$ref": "#/$defs/PostPlatformSettings",
          "description": "The platform settings this target was created with, echoed back in the same shape the create request accepts. For X and Threads threads, each `threadItems[].mediaItems` entry carries the hosted `url` of the stored media."
        }
      }
    },
    "BlueskySettings": {
      "type": "object",
      "properties": {
        "altTexts": {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 2000
          },
          "description": "Alt text for each image, matched to the media by order. Each entry is limited to 2000 characters."
        },
        "languages": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "maxItems": 3,
          "description": "Up to 3 BCP-47 language codes (e.g. `en`, `pt-BR`) declaring the languages of the post text."
        },
        "disableLinkCard": {
          "type": "boolean",
          "description": "When true, PostZen skips generating an external link preview card for the first URL in the post."
        }
      }
    },
    "FacebookSettings": {
      "type": "object",
      "properties": {
        "link": {
          "type": "string",
          "format": "uri"
        },
        "firstComment": {
          "type": "string"
        }
      }
    },
    "InstagramSettings": {
      "type": "object",
      "description": "Instagram target settings. `postType` selects the format: `feed` and `story` take exactly one media item, `reel` takes exactly one video, and `carousel` takes 2–10 media items (images and videos may be mixed). Captions are limited to 2,200 characters.",
      "properties": {
        "postType": {
          "type": "string",
          "enum": [
            "feed",
            "story",
            "reel",
            "carousel"
          ],
          "default": "feed",
          "description": "Instagram post format. `feed` (default) and `story` publish a single media item; `reel` publishes a single video; `carousel` publishes 2–10 ordered media items and may mix images and videos. Sending multiple media items with `feed` returns a validation error directing you to `carousel`."
        },
        "collaborators": {
          "type": "array",
          "description": "Up to three Instagram usernames to invite as collaborators. Supported on feed, reel, and carousel posts.",
          "items": {
            "type": "string"
          }
        },
        "userTags": {
          "type": "array",
          "description": "Photo tags with relative `x`/`y` coordinates from 0 to 1. Feed posts only — user tags are not supported on carousels, reels, or stories.",
          "items": {
            "type": "object",
            "required": [
              "username",
              "x",
              "y"
            ],
            "properties": {
              "username": {
                "type": "string"
              },
              "x": {
                "type": "number"
              },
              "y": {
                "type": "number"
              }
            }
          }
        },
        "firstComment": {
          "type": "string",
          "description": "Posts a first comment after publishing. Supported on feed, reel, and carousel posts. Maximum 2,200 characters."
        },
        "shareToFeed": {
          "type": "boolean",
          "description": "Reels only. Defaults to `true`. Set to `false` to keep the reel off the profile feed."
        },
        "trialParams": {
          "type": "object",
          "description": "Reels only. Publishes the reel as a trial reel, which Instagram shows to non-followers first. Sending it with any other `postType` returns a validation error. Trial reels are available only on public professional accounts that Instagram has made eligible; an ineligible account fails at publish time.",
          "required": [
            "graduationStrategy"
          ],
          "properties": {
            "graduationStrategy": {
              "type": "string",
              "enum": [
                "MANUAL",
                "SS_PERFORMANCE"
              ],
              "description": "How the trial reel graduates to followers. `MANUAL`: the creator graduates it in the Instagram app. `SS_PERFORMANCE`: Instagram graduates it automatically when it performs well with non-followers. Case-sensitive."
            }
          }
        }
      }
    },
    "LinkedInSettings": {
      "type": "object",
      "description": "LinkedIn target settings. A LinkedIn post carries exactly one media kind: no media (text only), 1–10 images (LinkedIn itself allows 20, but `mediaItems` caps at 10 items on every platform), one MP4 video, or one PDF document uploaded through `POST /v1/media/presign` with `contentType: \"application/pdf\"` (external document URLs are not ingested, and DOC/DOCX/PPT/PPTX cannot be published through the API). Commentary is limited to 3,000 characters. Every key below is also accepted in `snake_case` (for example `first_comment` and `organization_urn`).",
      "properties": {
        "visibility": {
          "type": "string",
          "enum": [
            "PUBLIC",
            "CONNECTIONS"
          ],
          "default": "PUBLIC",
          "description": "Who can see the post. Matched case-insensitively; an empty string or `null` counts as unset (defaults to `PUBLIC`), and any other non-empty value returns `400` with `settings.visibility must be PUBLIC or CONNECTIONS`. `CONNECTIONS` is only valid for a member (personal profile) post — combining it with `organizationUrn` is a validation error, because a company page has no connections."
        },
        "videoTitle": {
          "type": "string",
          "maxLength": 200,
          "description": "Optional title for video posts, shown on the LinkedIn video player. Ignored for non-video posts."
        },
        "documentTitle": {
          "type": "string",
          "maxLength": 200,
          "description": "Title for a document (PDF carousel) post. LinkedIn requires a title on document posts; when this is omitted PostZen falls back to the uploaded file's name. Ignored for non-document posts."
        },
        "organizationUrn": {
          "type": "string",
          "pattern": "^(urn:li:organization:[0-9]+|[0-9]+)$",
          "description": "Not available yet: company-page posting is waiting on LinkedIn's approval of PostZen's Community Management API access. Setting this (or an alias) today fails validation with `400` and a message prefixed with the target account's display name, for example `Jane Doe: LinkedIn company-page posting is not available yet, pending LinkedIn's approval. Remove settings.organizationUrn to publish to the connected member's profile.`, before anything is stored. On `PATCH /v1/posts/{postId}` the check applies to the `platforms` you send; omitting `platforms` leaves stored targets unchecked, and a stored company-page target fails at publish time instead. Once available, this publishes as a LinkedIn company page instead of the connected member. Accepts either the full URN (`urn:li:organization:12345`) or the bare numeric page id (`12345`), which PostZen expands to the URN. The connection must hold `w_organization_social`; one that does not gets `400` with `<account name>: Reconnect this LinkedIn account to post as a company page.`. Also accepted as `organizationId` / `organization_id`."
        },
        "firstComment": {
          "type": "string",
          "maxLength": 1250,
          "description": "Comment posted by the same author immediately after the post goes live. LinkedIn's comment composer caps this at 1,250 characters, tighter than the 3,000-character post body. Best-effort: a failure here is logged and never fails the post, and the post is never retried because of it. Not available yet on LinkedIn: first comments wait on the same LinkedIn approval as company-page posting. Today the comment is dropped before the post is stored (the 1,250-character limit is not applied to it), the post still publishes, and the response carries a top-level `warnings` entry prefixed with the target account's display name, for example `Jane Doe: LinkedIn first comments are not available yet; this post publishes without the comment.`"
        },
        "disableLinkPreview": {
          "type": "boolean",
          "description": "LinkedIn's Posts API never scrapes URLs, so a bare link renders as plain text. When this is `false` or omitted and the text contains a URL, PostZen attaches a link card for the first URL; because no scraped metadata is available, the card is titled with the URL's hostname (for example `example.com`). Set to `true` to keep the post as plain text with no card. Also accepted as `disableLinkCard`."
        },
        "reshareUrl": {
          "type": "string",
          "description": "LinkedIn post to quote-reshare. Accepts a public post permalink or a `urn:li:activity:` / `urn:li:share:` / `urn:li:ugcPost:` URN. Mutually exclusive with uploaded media."
        },
        "geoRestrictionCountries": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[A-Z]{2}$"
          },
          "maxItems": 25,
          "description": "Restrict who sees the post to these countries, as uppercase ISO 3166-1 alpha-2 codes (for example `[\"US\", \"CA\"]`). Up to 25 countries, and organization posts only — supplying this without `organizationUrn` is a validation error. Not available yet, because it requires `organizationUrn`."
        }
      }
    },
    "PinterestSettings": {
      "type": "object",
      "required": [
        "boardId"
      ],
      "properties": {
        "boardId": {
          "type": "string",
          "description": "Pinterest board to publish the pin to."
        },
        "title": {
          "type": "string",
          "description": "Pin title."
        },
        "link": {
          "type": "string",
          "format": "uri",
          "description": "Destination link for the pin."
        },
        "altText": {
          "type": "string"
        },
        "coverImageUrl": {
          "type": "string",
          "format": "uri",
          "description": "Cover or thumbnail image URL for video pins."
        },
        "coverImageKeyFrameTime": {
          "type": "number",
          "minimum": 0,
          "description": "Cover keyframe time in seconds for video pins, as an alternative to coverImageUrl."
        }
      }
    },
    "PostMediaItem": {
      "type": "object",
      "required": [
        "url"
      ],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "PostZen-hosted `publicUrl` from `POST /v1/media/presign`, or an external image/video URL. External URLs are downloaded and re-hosted by PostZen; they must resolve to an image or video (PDF is not supported) of at most 100 MB."
        },
        "title": {
          "type": "string",
          "description": "Optional alt text/title for the media item."
        }
      }
    },
    "PostPlatformSettings": {
      "description": "Platform-specific publishing options. Unknown keys are ignored.",
      "oneOf": [
        {
          "$ref": "#/$defs/InstagramSettings"
        },
        {
          "$ref": "#/$defs/FacebookSettings"
        },
        {
          "$ref": "#/$defs/ThreadsSettings"
        },
        {
          "$ref": "#/$defs/TikTokSettings"
        },
        {
          "$ref": "#/$defs/LinkedInSettings"
        },
        {
          "$ref": "#/$defs/XSettings"
        },
        {
          "$ref": "#/$defs/YouTubeSettings"
        },
        {
          "$ref": "#/$defs/PinterestSettings"
        },
        {
          "$ref": "#/$defs/BlueskySettings"
        },
        {
          "$ref": "#/$defs/TelegramSettings"
        }
      ]
    },
    "PublicPlatformInput": {
      "type": "string",
      "enum": [
        "twitter",
        "x",
        "instagram",
        "tiktok",
        "linkedin",
        "facebook",
        "youtube",
        "threads",
        "pinterest",
        "bluesky",
        "telegram"
      ]
    },
    "TelegramSettings": {
      "type": "object",
      "description": "Telegram target settings. Text-only posts allow 4,096 characters; attaching any media caps the text at 1,024 characters as a caption. A post carries 1-10 media items and may mix photos and videos in one album, but a GIF must be posted on its own. Telegram reports no post analytics.",
      "properties": {
        "parseMode": {
          "type": "string",
          "enum": [
            "html",
            "markdownv2"
          ],
          "description": "Formatting mode for the message or caption. Omit to send plain text, which is the default. `html` is recommended: it only requires escaping `<`, `>`, and `&`, whereas `markdownv2` requires escaping every one of `_ * [ ] ( ) ~ ` > # + - = | { } . !` and rejects the whole message otherwise."
        },
        "disableNotification": {
          "type": "boolean",
          "description": "When true, members receive the post silently, with no sound or vibration."
        },
        "disableLinkPreview": {
          "type": "boolean",
          "description": "When true, suppresses the link preview card for URLs in the text. Applies to text-only posts; a post with media has no link preview."
        },
        "protectContent": {
          "type": "boolean",
          "description": "When true, Telegram blocks forwarding and saving of the post."
        }
      }
    },
    "ThreadsSettings": {
      "type": "object",
      "properties": {
        "replyControl": {
          "type": "string",
          "enum": [
            "everyone",
            "accountsYouFollow",
            "mentionedOnly"
          ],
          "description": "Who can reply. Omit to let everyone reply. When threadItems is set, applies only to the first post."
        },
        "threadItems": {
          "type": "array",
          "minItems": 1,
          "maxItems": 25,
          "description": "Publish this target as a thread of 1–25 posts, in order. The first item is the root post and each later item is published as a reply to the previous one. When set, the target's `content`/`customContent` and the post's top-level `mediaItems` are not published to Threads; they still apply to the post's other targets. `platformPostUrl` on the result is the root post's URL. A one-item thread publishes like a plain post. Each item supports up to 500 characters and 10 images/videos. `replyControl` applies only to the first post.",
          "items": {
            "$ref": "#/$defs/ThreadsThreadItem"
          }
        }
      },
      "description": "Threads target settings. Set `threadItems` to publish a chain of 1–25 posts, each with up to 500 characters and 10 images/videos. The first item is the root and each later item replies to the previous one. When set, the target's `content`/`customContent` and the post's top-level `mediaItems` are not published to Threads; they still apply to other targets. `replyControl` applies only to the first post."
    },
    "ThreadsThreadItem": {
      "type": "object",
      "description": "One post in a Threads thread. Each item needs text, media, or both.",
      "required": [
        "content"
      ],
      "properties": {
        "content": {
          "type": "string",
          "maxLength": 500,
          "description": "Text of this post in the thread, up to 500 characters. May be empty only when the item has `mediaItems`."
        },
        "mediaItems": {
          "type": "array",
          "maxItems": 10,
          "description": "Up to 10 images/videos attached to this post, in the same format as the post's top-level `mediaItems`. Images (including GIF media) and videos can be mixed within an item.",
          "items": {
            "$ref": "#/$defs/PostMediaItem"
          }
        }
      }
    },
    "TikTokSettings": {
      "type": "object",
      "properties": {
        "privacyLevel": {
          "type": "string",
          "enum": [
            "publicToEveryone",
            "mutualFollowFriends",
            "followerOfCreator",
            "selfOnly"
          ]
        },
        "allowComments": {
          "type": "boolean"
        },
        "allowDuet": {
          "type": "boolean"
        },
        "allowStitch": {
          "type": "boolean"
        },
        "disableComment": {
          "type": "boolean"
        },
        "disableDuet": {
          "type": "boolean"
        },
        "disableStitch": {
          "type": "boolean"
        },
        "videoCoverTimestampMs": {
          "type": "number"
        },
        "uploadAsDraft": {
          "type": "boolean"
        },
        "brandContentToggle": {
          "type": "boolean"
        },
        "brandOrganicToggle": {
          "type": "boolean"
        },
        "isAigc": {
          "type": "boolean",
          "default": false,
          "description": "Marks the post as AI-generated. TikTok labels it \"Creator labeled as AI-generated\", which TikTok's Community Guidelines require for realistic AI-made video, images, or audio. Sent as `post_info.is_aigc` on video posts and as the top-level `is_aigc` field on photo posts. The label cannot be added or removed after the post is published, and TikTok's inbox endpoint has no such field, so it is ignored when `uploadAsDraft` is true: set the label in the TikTok app instead. Also accepted as `is_aigc` and `aiGenerated`."
        }
      }
    },
    "XSettings": {
      "type": "object",
      "description": "X target settings. A single X post carries up to 280 characters and 1–4 images, one video, or one GIF. Set `threadItems` to publish a thread instead: the first item is the root post and each later item is published as a reply to the one before it. When `threadItems` is set, this target's `content`/`customContent` and the post's top-level `mediaItems` are not published to X — each item carries its own text and media — but they still apply to the post's other targets.",
      "properties": {
        "replySettings": {
          "type": "string",
          "enum": [
            "following",
            "mentionedUsers"
          ],
          "description": "Who can reply to the post. Omit to let everyone reply. On a thread this applies to the root post, which is where X enforces reply restrictions for the whole conversation."
        },
        "threadItems": {
          "type": "array",
          "minItems": 1,
          "maxItems": 25,
          "description": "Publish this target as a thread of 1–25 posts, in order. The first item is the root post and each later item is published as a reply to the previous one. When set, the target's `content`/`customContent` and the post's top-level `mediaItems` are not published to X; they still apply to the post's other targets. `platformPostUrl` on the result is the root post's URL. A one-item thread publishes like a plain post.",
          "items": {
            "$ref": "#/$defs/XThreadItem"
          }
        }
      }
    },
    "XThreadItem": {
      "type": "object",
      "description": "One post in an X thread. Each item needs text, media, or both.",
      "required": [
        "content"
      ],
      "properties": {
        "content": {
          "type": "string",
          "maxLength": 280,
          "description": "Text of this post in the thread, up to 280 characters. May be empty only when the item has `mediaItems`."
        },
        "mediaItems": {
          "type": "array",
          "maxItems": 4,
          "description": "Media attached to this post in the thread, in the same format as the post's top-level `mediaItems`: 1–4 images, or one video, or one GIF. Images and videos cannot be mixed within an item.",
          "items": {
            "$ref": "#/$defs/PostMediaItem"
          }
        }
      }
    },
    "YouTubeSettings": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        },
        "privacyStatus": {
          "type": "string",
          "enum": [
            "public",
            "unlisted",
            "private"
          ]
        },
        "tags": {
          "oneOf": [
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "string",
              "description": "Comma-separated tags."
            }
          ]
        },
        "categoryId": {
          "type": "string"
        },
        "madeForKids": {
          "type": "boolean"
        },
        "notifySubscribers": {
          "type": "boolean"
        }
      }
    }
  }
}