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 |
JSON Schema
{
"$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.
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.