postzen-dev · Schema

CreatePostRequest

Provide exactly one creation mode: `publishNow`, `scheduledFor`, `isDraft`, or `queuedFromProfile`. `platforms` is required unless `isDraft` is true.

Social MediaDeveloper ToolsAI AgentsAutomation

Properties

Name Type Description
title string Internal post title. YouTube uses this as the fallback video title when `settings.title` is omitted.
content string Shared post text. Platform-specific validation still applies.
mediaItems array Duplicate URLs are removed before the post is created.
platforms array
scheduledFor string ISO 8601 date for scheduled posts. Must be at least 60 seconds in the future.
publishNow boolean Publish synchronously where possible.
isDraft boolean Create a draft. `platforms` is optional for drafts.
queuedFromProfile string Profile id whose queue places the post. It can be any profile the API key can access and does not have to hold the target accounts; it is required when the accounts span more than one profile. PostZen
queueId string Specific queue on `queuedFromProfile`. Defaults to that profile's default queue. Requires `queuedFromProfile`.
timezone string Ignored in queue mode; queued posts take the queue's timezone.
tags array
View JSON Schema on GitHub

JSON Schema

postzen-dev-create-post-request-schema.json Raw ↑
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/postzen-dev/json-schema/postzen-dev-create-post-request-schema.json",
  "title": "CreatePostRequest",
  "description": "Provide exactly one creation mode: `publishNow`, `scheduledFor`, `isDraft`, or `queuedFromProfile`. `platforms` is required unless `isDraft` is true.",
  "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/CreatePostRequest",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Internal post title. YouTube uses this as the fallback video title when `settings.title` is omitted."
    },
    "content": {
      "type": "string",
      "default": "",
      "description": "Shared post text. Platform-specific validation still applies."
    },
    "mediaItems": {
      "type": "array",
      "maxItems": 10,
      "description": "Duplicate URLs are removed before the post is created.",
      "items": {
        "$ref": "#/$defs/PostMediaItem"
      }
    },
    "platforms": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/CreatePostTarget"
      }
    },
    "scheduledFor": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 date for scheduled posts. Must be at least 60 seconds in the future."
    },
    "publishNow": {
      "type": "boolean",
      "description": "Publish synchronously where possible."
    },
    "isDraft": {
      "type": "boolean",
      "description": "Create a draft. `platforms` is optional for drafts."
    },
    "queuedFromProfile": {
      "type": "string",
      "description": "Profile id whose queue places the post. It can be any profile the API key can access and does not have to hold the target accounts; it is required when the accounts span more than one profile. PostZen assigns the next free slot and returns it as `scheduledFor`. Do not call `GET /v1/queue/next-slot` and pass the result as `scheduledFor`: the slot is only claimed by the create call itself, so a fetched slot can be taken by another request before yours arrives, and the post would be scheduled outside the queue."
    },
    "queueId": {
      "type": "string",
      "description": "Specific queue on `queuedFromProfile`. Defaults to that profile's default queue. Requires `queuedFromProfile`."
    },
    "timezone": {
      "type": "string",
      "default": "UTC",
      "description": "Ignored in queue mode; queued posts take the queue's timezone."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "$defs": {
    "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."
        }
      }
    },
    "CreatePostTarget": {
      "type": "object",
      "required": [
        "platform",
        "accountId"
      ],
      "properties": {
        "platform": {
          "$ref": "#/$defs/PublicPlatformInput"
        },
        "accountId": {
          "type": "string",
          "description": "PostZen account id or provider account id."
        },
        "customContent": {
          "type": "string",
          "description": "Overrides shared `content` for this platform."
        },
        "settings": {
          "$ref": "#/$defs/PostPlatformSettings"
        }
      }
    },
    "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"
        }
      }
    }
  }
}

Work with this as data

Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for schemas

4 MCP tools reach this
  • find_json_schemasBrowse and filter every JSON Schema in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/postzen-dev-create-post-request"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.