Publishing · Posts

Create post

Creates a post.

POSThttps://api.pozy.ai/v1/posts

createPost

Guides: Create a post, Scheduling and timezones, Drafts and approvals

Request

Send your API key as Authorization: Bearer pz_live_.... Read-only keys cannot call it. Keys with the publishing resource group disabled get 403 resource_group_disabled. Authentication

Headers

Name	Type	Notes
`Idempotency-Key`	string	Up to 255 charactersRetries with the same key return the original result. See Idempotency
`x-request-id`	string (uuid)	Your own id for this request, echoed back in `X-Request-Id`

Request body

application/json, required

titlestring
contentstring
mediaItemsarray of object
13 child fields
- typestring
  One of image, video, gif, document.
- urlstring (URL)
- fileIdstring
- accountIdstring
- titlestring
- altTextstring
- filenamestring
- sizeinteger
- mimeTypestring
- thumbnailstring (URL)
- instagramThumbnailstring (URL)
- subtitlesarray of object
  Up to 20 items.
  2 child fields
  urlstring (URL)required
  languagestringrequired
- tiktokProcessedboolean
platformsarray of object
- platformstringrequired
- accountIdstringrequired
- customContentstring
- customMediaarray of object
  13 child fields
  - typestring
    One of image, video, gif, document.
  - urlstring (URL)
  - fileIdstring
  - accountIdstring
  - titlestring
  - altTextstring
  - filenamestring
  - sizeinteger
  - mimeTypestring
  - thumbnailstring (URL)
  - instagramThumbnailstring (URL)
  - subtitlesarray of object
    Up to 20 items.
    2 child fields
    urlstring (URL)required
    languagestringrequired
  - tiktokProcessedboolean
- scheduledForstring (date-time)
- platformSpecificDataobject
  One of:
  X settings (12 fields)
  articleobject
  4 child fields
  titlestringrequired
  content_stateobjectrequired
  2 child fields
  blocksarray of objectrequired
  At least 1 item.
  6 child fields
  typestringrequired
  One of unstyled, header-one, header-two, header-three, unordered-list-item, ordered-list-item, blockquote, atomic.
  textstringrequired
  keystring
  dataobject
  4 child fields
  cashtagsarray of object
  hashtagsarray of object
  mentionsarray of object
  urlsarray of object
  inline_style_rangesarray of object
  3 child fields
  offsetintegerrequired
  At least 0.
  lengthintegerrequired
  At least 0.
  stylestringrequired
  One of bold, italic, strikethrough.
  entity_rangesarray of object
  3 child fields
  keyintegerrequired
  At least 0.
  offsetintegerrequired
  At least 0.
  lengthintegerrequired
  At least 0.
  entitiesarray of objectrequired
  One of:
  Option 1 (2 fields)
  keystringrequired
  valueobjectrequired
  3 child fields
  typestringrequired
  Always post.
  mutabilitystringrequired
  One of immutable, mutable, segmented.
  dataobjectrequired
  Option 2 (2 fields)
  keystringrequired
  valueobjectrequired
  3 child fields
  typestringrequired
  Always link.
  mutabilitystringrequired
  One of immutable, mutable, segmented.
  dataobjectrequired
  Option 3 (2 fields)
  keystringrequired
  valueobjectrequired
  3 child fields
  typestringrequired
  Always image.
  mutabilitystringrequired
  One of immutable, mutable, segmented.
  dataobjectrequired
  Option 4 (2 fields)
  keystringrequired
  valueobjectrequired
  3 child fields
  typestringrequired
  Always emoji.
  mutabilitystringrequired
  One of immutable, mutable, segmented.
  dataobjectrequired
  Option 5 (2 fields)
  keystringrequired
  valueobjectrequired
  3 child fields
  typestringrequired
  Always markdown.
  mutabilitystringrequired
  One of immutable, mutable, segmented.
  dataobjectrequired
  Option 6 (2 fields)
  keystringrequired
  valueobjectrequired
  3 child fields
  typestringrequired
  One of divider, latex.
  mutabilitystringrequired
  One of immutable, mutable, segmented.
  dataobjectrequired
  modestring
  One of publish, draft. Default publish.
  coverobject
  2 child fields
  urlstring (URL)required
  Matches ^https?://.+\.(?:[jJ][pP][eE]?[gG]|[pP][nN][gG]|[wW][eE][bB][pP])(?:[?#].*)?$.
  altTextstring
  Up to 1000 characters.
  replyToTweetIdstring
  quoteTweetIdstring
  replySettingsstring
  One of following, mentionedUsers, subscribers, verified.
  threadItemsarray of object
  2 child fields
  contentstring
  mediaItemsarray of object
  13 child fields
  typestring
  One of image, video, gif, document.
  urlstring (URL)
  fileIdstring
  accountIdstring
  titlestring
  altTextstring
  filenamestring
  sizeinteger
  mimeTypestring
  thumbnailstring (URL)
  instagramThumbnailstring (URL)
  subtitlesarray of object
  Up to 20 items.
  2 child fields
  urlstring (URL)required
  languagestringrequired
  tiktokProcessedboolean
  pollobject
  2 child fields
  optionsarray of stringrequired
  At least 2 items. Up to 4 items. Each item: 1 to 25 characters.
  duration_minutesintegerrequired
  5 to 10080.
  longVideoboolean
  Default false.
  geoRestrictionobject
  1 child field
  countriesarray of stringrequired
  At least 1 item. Up to 25 items. Each item: matches ^[A-Z]{2}$.
  paidPartnershipboolean
  Default false.
  madeWithAiboolean
  Default false.
  sensitiveMediaobject
  3 child fields
  adultContentboolean
  graphicViolenceboolean
  otherboolean
  mediaTaggedUsersarray of string
  Up to 10 items. Each item: matches ^@?\w{1,15}$.
  Threads settings (3 fields)
  topic_tagstring
  1 to 50 characters.
  firstCommentstring
  Up to 500 characters.
  threadItemsarray of object
  2 child fields
  contentstring
  mediaItemsarray of object
  13 child fields
  typestring
  One of image, video, gif, document.
  urlstring (URL)
  fileIdstring
  accountIdstring
  titlestring
  altTextstring
  filenamestring
  sizeinteger
  mimeTypestring
  thumbnailstring (URL)
  instagramThumbnailstring (URL)
  subtitlesarray of object
  Up to 20 items.
  2 child fields
  urlstring (URL)required
  languagestringrequired
  tiktokProcessedboolean
  Facebook settings (6 fields)
  contentTypestring
  One of story, reel.
  titlestring
  firstCommentstring
  pageIdstring
  geoRestrictionobject
  1 child field
  countriesarray of stringrequired
  At least 1 item. Up to 25 items. Each item: matches ^[A-Z]{2}$.
  facebookSettingsobject
  4 child fields
  draftboolean
  Default false.
  carouselCardsarray of object
  At least 2 items. Up to 10 items.
  3 child fields
  linkstring (URL)required
  namestring
  Up to 255 characters.
  descriptionstring
  Up to 255 characters.
  carouselLinkstring (URL)
  textFormatPresetIdstring
  Matches ^\d+$.
  Instagram settings (17 fields)
  contentTypestring
  One of story.
  shareToFeedboolean
  Default true.
  collaboratorsarray of string
  firstCommentstring
  trialParamsobject
  1 child field
  graduationStrategystring
  One of MANUAL, SS_PERFORMANCE.
  userTagsarray of object
  4 child fields
  usernamestringrequired
  xnumber
  0 to 1.
  ynumber
  0 to 1.
  mediaIndexinteger
  At least 0.
  audioNamestring
  audioConfigurationobject
  3 child fields
  audioIdstringrequired
  audioVolumeinteger
  0 to 100.
  videoVolumeinteger
  0 to 100.
  muteAudioboolean
  Default false.
  thumbOffsetinteger
  At least 0.
  instagramThumbnailstring (URL)
  reelCoverstring (URL)
  isAiGeneratedboolean
  Default false.
  isPaidPartnershipboolean
  Default false.
  brandedContentSponsorsarray of string
  Up to 2 items.
  commentsEnabledboolean
  Default true.
  locationIdstring
  Matches ^[0-9]+$.
  Linked In settings (8 fields)
  documentTitlestring
  organizationUrnstring
  firstCommentstring
  disableLinkPreviewboolean
  audienceobject
  10 child fields
  countriesarray of string
  Up to 25 items.
  geoLocationsarray of string
  interfaceLocalesarray of object
  2 child fields
  languagestringrequired
  countrystringrequired
  industriesarray of string
  jobFunctionsarray of string
  senioritiesarray of string
  staffCountRangesarray of string
  Each item: one of SIZE_1, SIZE_2_TO_10, SIZE_11_TO_50, SIZE_51_TO_200, SIZE_201_TO_500, SIZE_501_TO_1000, SIZE_1001_TO_5000, SIZE_5001_TO_10000, SIZE_10001_OR_MORE.
  degreesarray of string
  fieldsOfStudyarray of string
  organizationsarray of string
  reshareUrlstring
  geoRestrictionobject
  1 child field
  countriesarray of stringrequired
  At least 1 item. Up to 25 items. Each item: matches ^[A-Z]{2}$.
  pollobject
  3 child fields
  questionstringrequired
  1 to 140 characters.
  optionsarray of stringrequired
  At least 2 items. Up to 4 items. Each item: 1 to 30 characters.
  durationstring
  One of ONE_DAY, THREE_DAYS, SEVEN_DAYS, FOURTEEN_DAYS. Default SEVEN_DAYS.
  Pinterest settings (7 fields)
  titlestring
  Up to 100 characters.
  boardIdstring
  boardSectionIdstring
  linkstring (URL)
  coverImageUrlstring (URL)
  coverImageKeyFrameTimeinteger
  isAiGeneratedboolean
  Default false.
  You Tube settings (8 fields)
  titlestring
  Up to 100 characters.
  visibilitystring
  One of public, private, unlisted. Default public.
  madeForKidsboolean
  Default false.
  firstCommentstring
  Up to 10000 characters.
  containsSyntheticMediaboolean
  Default false.
  notifySubscribersboolean
  Default true.
  categoryIdstring
  Default 22.
  playlistIdstring
  Google Business settings (6 fields)
  locationIdstring
  languageCodestring
  topicTypestring
  One of STANDARD, EVENT, OFFER. Default STANDARD.
  callToActionobject
  2 child fields
  typestringrequired
  One of LEARN_MORE, BOOK, ORDER, SHOP, SIGN_UP, CALL.
  urlstring (URL)required
  eventobject
  2 child fields
  titlestringrequired
  scheduleobjectrequired
  4 child fields
  startDateobjectrequired
  3 child fields
  yearintegerrequired
  monthintegerrequired
  1 to 12.
  dayintegerrequired
  1 to 31.
  startTimeobject
  2 child fields
  hoursinteger
  0 to 23.
  minutesinteger
  0 to 59.
  endDateobjectrequired
  3 child fields
  yearintegerrequired
  monthintegerrequired
  1 to 12.
  dayintegerrequired
  1 to 31.
  endTimeobject
  2 child fields
  hoursinteger
  0 to 23.
  minutesinteger
  0 to 59.
  offerobject
  3 child fields
  redeemOnlineUrlstring (URL)
  termsConditionsstring
  couponCodestring
  Tik Tok settings (22 fields)
  draftboolean
  privacyLevelstring
  allowCommentboolean
  allowDuetboolean
  allowStitchboolean
  commercialContentTypestring
  One of none, brand_organic, brand_content.
  brandPartnerPromoteboolean
  isBrandOrganicPostboolean
  contentPreviewConfirmedboolean
  expressConsentGivenboolean
  mediaTypestring
  One of video, photo.
  videoCoverTimestampMsinteger
  At least 0.
  videoCoverImageUrlstring (URL)
  photoCoverIndexinteger
  At least 0.
  autoAddMusicboolean
  musicSoundInfoobject
  4 child fields
  musicSoundIdstringrequired
  musicSoundVolumeinteger
  Default 50. 0 to 100.
  musicSoundStartinteger
  At least 0.
  musicSoundEndinteger
  At least 0.
  videoOriginalSoundVolumeinteger
  0 to 100.
  videoMadeWithAiboolean
  locationIdstring
  locationNamestring
  isAdsOnlyboolean
  descriptionstring
  Up to 4000 characters.
  Telegram settings (4 fields)
  parseModestring
  One of HTML, Markdown, MarkdownV2.
  disableWebPagePreviewboolean
  disableNotificationboolean
  protectContentboolean
  Snapchat settings (1 fields)
  contentTypestring
  One of story, saved_story, spotlight. Default story.
  Reddit settings (12 fields)
  subredditstring
  titlestring
  Up to 300 characters.
  urlstring (URL)
  forceSelfboolean
  flairIdstring
  flairTextstring
  nsfwboolean
  Default false.
  spoilerboolean
  Default false.
  sendrepliesboolean
  Default true.
  nativeVideoboolean
  Default true.
  videogifboolean
  videoPosterUrlstring (URL)
  Bluesky settings (2 fields)
  langsarray of string
  At least 1 item. Up to 3 items.
  threadItemsarray of object
  2 child fields
  contentstring
  mediaItemsarray of object
  13 child fields
  typestring
  One of image, video, gif, document.
  urlstring (URL)
  fileIdstring
  accountIdstring
  titlestring
  altTextstring
  filenamestring
  sizeinteger
  mimeTypestring
  thumbnailstring (URL)
  instagramThumbnailstring (URL)
  subtitlesarray of object
  Up to 20 items.
  2 child fields
  urlstring (URL)required
  languagestringrequired
  tiktokProcessedboolean
  Discord settings (10 fields)
  channelIdstringrequired
  embedsarray of object
  Up to 10 items.
  9 child fields
  titlestring
  descriptionstring
  urlstring
  colorinteger
  imageobject
  1 child field
  urlstring
  thumbnailobject
  1 child field
  urlstring
  footerobject
  2 child fields
  textstring
  icon_urlstring
  authorobject
  3 child fields
  namestring
  urlstring
  icon_urlstring
  fieldsarray of object
  Up to 25 items.
  3 child fields
  namestringrequired
  valuestringrequired
  inlineboolean
  pollobject
  4 child fields
  questionobject
  1 child field
  textstringrequired
  answersarray of object
  Up to 10 items.
  1 child field
  poll_mediaobject
  1 child field
  textstring
  durationinteger
  1 to 768.
  allow_multiselectboolean
  crosspostboolean
  forumThreadNamestring
  forumAppliedTagsarray of string
  Up to 5 items.
  threadFromMessageobject
  3 child fields
  namestring
  autoArchiveDurationinteger
  One of 60, 1440, 4320, 10080.
  rateLimitPerUserinteger
  0 to 21600.
  ttsboolean
  webhookUsernamestring
  webhookAvatarUrlstring
  Slack settings (5 fields)
  threadTsstring
  unfurlLinksboolean
  unfurlMediaboolean
  usernamestring
  iconUrlstring
scheduledForstring (date-time)
publishNowboolean
Default false.
isDraftboolean
Default false.
requiresApprovalboolean
Default false.
dryRunboolean
Default false.
timezonestring
tagsarray of string
hashtagsarray of string
mentionsarray of string
crosspostingEnabledboolean
Default true.
metadataobject
tiktokSettingsobject
22 child fields
- draftboolean
- privacyLevelstring
- allowCommentboolean
- allowDuetboolean
- allowStitchboolean
- commercialContentTypestring
  One of none, brand_organic, brand_content.
- brandPartnerPromoteboolean
- isBrandOrganicPostboolean
- contentPreviewConfirmedboolean
- expressConsentGivenboolean
- mediaTypestring
  One of video, photo.
- videoCoverTimestampMsinteger
  At least 0.
- videoCoverImageUrlstring (URL)
- photoCoverIndexinteger
  At least 0.
- autoAddMusicboolean
- musicSoundInfoobject
  4 child fields
  musicSoundIdstringrequired
  musicSoundVolumeinteger
  Default 50. 0 to 100.
  musicSoundStartinteger
  At least 0.
  musicSoundEndinteger
  At least 0.
- videoOriginalSoundVolumeinteger
  0 to 100.
- videoMadeWithAiboolean
- locationIdstring
- locationNamestring
- isAdsOnlyboolean
- descriptionstring
  Up to 4000 characters.
facebookSettingsobject
- draftboolean
  Default false.
- carouselCardsarray of object
  At least 2 items. Up to 10 items.
  3 child fields
  - linkstring (URL)required
  - namestring
    Up to 255 characters.
  - descriptionstring
    Up to 255 characters.
- carouselLinkstring (URL)
- textFormatPresetIdstring
  Matches ^\d+$.
recyclingobject
7 child fields
- enabledboolean
  Default true.
- gapinteger
  At least 1.
- gapFreqstring
  One of week, month. Default month.
- startDatestring (date-time)
- expireCountinteger
  At least 1. Can be null.
- expireDatestring (date-time)
  Can be null.
- contentVariationsarray of string
  Up to 20 items.
queuedFromProfilestring
queueIdstring

Example

curl -X POST "https://api.pozy.ai/v1/posts" \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Launch day",
  "content": "Hello from Pozy",
  "mediaItems": [
    {
      "type": "image",
      "url": "https://pozy.ai/media/example-1.jpg",
      "fileId": "6035bf6bd3aac3067c336c50"
    }
  ],
  "platforms": [
    {
      "platform": "instagram",
      "accountId": "696e0b682d0a31188e7a2ba9"
    }
  ]
}'

import { randomUUID } from "node:crypto";

const res = await fetch("https://api.pozy.ai/v1/posts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Launch day",
    content: "Hello from Pozy",
    mediaItems: [
      {
        type: "image",
        url: "https://pozy.ai/media/example-1.jpg",
        fileId: "6035bf6bd3aac3067c336c50"
      }
    ],
    platforms: [
      {
        platform: "instagram",
        accountId: "696e0b682d0a31188e7a2ba9"
      }
    ]
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data?.error ?? `Request failed with status ${res.status}`);
console.log(data);

import os
import requests

resp = requests.post(
    "https://api.pozy.ai/v1/posts",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={
        "title": "Launch day",
        "content": "Hello from Pozy",
        "mediaItems": [
            {
                "type": "image",
                "url": "https://pozy.ai/media/example-1.jpg",
                "fileId": "6035bf6bd3aac3067c336c50",
            },
        ],
        "platforms": [
            {
                "platform": "instagram",
                "accountId": "696e0b682d0a31188e7a2ba9",
            },
        ],
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Response

200 on success

200 response

{
  "dryRun": true,
  "canPublish": true,
  "tiktok": [
    {
      "accountId": "696e0b682d0a31188e7a2ba9",
      "canPublish": true,
      "alreadyPostedToday": true,
      "reason": "string"
    }
  ]
}

Errors

Errors use one shape: { error, type, code, param?, details? }. The ones you are most likely to see here:

400	invalid_request_error	A parameter or body field is missing or invalid. `param` names it.
401	authentication_error	The API key is missing, revoked or expired.
403	permission_error	The key is read-only, scoped to other profiles, or has this resource group disabled.
429	rate_limit_error	Too many requests this minute. Wait for `Retry-After` seconds.

Every code is listed in Errors.