Publishing · Posts

Update post

Updates a post.

PUThttps://api.pozy.ai/v1/posts/{postId}

updatePost

Guides: Post lifecycle, Create a post, Scheduling and timezones

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

Path parameters

Name	Type	Notes
`postId`required	string

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
scheduledForstring (date-time)
publishNowboolean
Default false.
isDraftboolean
requiresApprovalboolean
timezonestring
visibilitystring
One of public, private, unlisted.
tagsarray of string
hashtagsarray of string
mentionsarray of string
crosspostingEnabledboolean
metadataobject
queuedFromProfilestring
queueIdstring
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.

Example

curl -X PUT "https://api.pozy.ai/v1/posts/6108a2cc742cb4e991051e0c" \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -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"
    }
  ]
}'

const res = await fetch("https://api.pozy.ai/v1/posts/6108a2cc742cb4e991051e0c", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "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.put(
    "https://api.pozy.ai/v1/posts/6108a2cc742cb4e991051e0c",
    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

messagestring
postobject
20 child fields
- _idstring
- userIdstring or object
  One of:
  string
  User (6 fields)
  _idstring
  emailstring
  namestring
  rolestring
  disabledResourceGroupsarray of string
  createdAtstring (date-time)
- 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
  19 child fields
  platformstring
  accountIdstring or object
  One of:
  string
  Social Account (19 fields)
  _idstringrequired
  platformstringrequired
  One of tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat, discord, slack, whatsapp, shopify, wordpress, wix, linkedinads, metaads, pinterestads, tiktokads, xads and 15 more.
  profileIdstring or objectrequired
  One of:
  string
  Profile (11 fields)
  _idstring
  userIdstring
  namestring
  descriptionstring
  colorstring
  timezonestring
  Can be null.
  externalIdstring
  Can be null.
  isDefaultboolean
  isOverLimitboolean
  accountCountinteger
  createdAtstring (date-time)
  usernamestring
  displayNamestring
  platformUserIdstring
  scopeAreasarray of string
  Can be null.
  oauthAppIdstring
  Can be null.
  tiktokAccountTypestring
  One of business, personal, unknown.
  profilePicturestring
  Can be null.
  profileUrlstring
  isActivebooleanrequired
  needsReconnectionboolean
  followersCountnumber
  followersLastUpdatedstring (date-time)
  parentAccountIdstring
  Can be null.
  enabledboolean
  rateLimitedUntilstring (date-time)
  Can be null.
  metadataobject
  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
  statusstring
  platformPostIdstring
  platformPostUrlstring
  Can be null.
  publishedAtstring (date-time)
  removedFromPlatformAtstring (date-time)
  Can be null.
  isTrialReelboolean
  trialGraduationStrategystring
  One of MANUAL, SS_PERFORMANCE.
  publishAttemptsinteger
  publishRetriesinteger
  errorMessagestring
  errorCategorystring
  One of auth_expired, user_content, user_abuse, account_issue, platform_rejected, platform_error, platform_rate_limit, quota_exhausted, system_error, unknown.
  errorSourcestring
  One of user, platform, system.
  platformErrorobject
  3 child fields
  codeinteger
  subcodeinteger
  messagestringrequired
- scheduledForstring (date-time)
- timezonestring
- statusstring
  One of draft, pending_approval, scheduled, publishing, published, partial, failed, cancelled.
- tagsarray of string
- hashtagsarray of string
- mentionsarray of string
- visibilitystring
  One of public, private, unlisted.
- metadataobject
- recyclingobject
  11 child fields
  enabledboolean
  gapinteger
  gapFreqstring
  One of week, month.
  startDatestring (date-time)
  expireCountinteger
  expireDatestring (date-time)
  contentVariationsarray of string
  contentVariationIndexinteger
  recycleCountinteger
  nextRecycleAtstring (date-time)
  lastRecycledAtstring (date-time)
- recycledFromPostIdstring
- queuedFromProfilestring
- queueIdstring
- createdAtstring (date-time)
- updatedAtstring (date-time)
warningsarray of string

200 response

{
  "message": "Hello from Pozy",
  "post": {
    "_id": "635d87e261ae344ef27fd1df",
    "userId": "6da95b9455a22c1e061837af",
    "title": "Launch day",
    "content": "Hello from Pozy",
    "mediaItems": [
      {
        "type": "image",
        "url": "https://pozy.ai/media/example-1.jpg",
        "fileId": "6035bf6bd3aac3067c336c50",
        "accountId": "696e0b682d0a31188e7a2ba9",
        "title": "Launch day",
        "altText": "Hello from Pozy",
        "filename": "photo.jpg",
        "size": 482133,
        "mimeType": "image/jpeg",
        "thumbnail": "https://pozy.ai/media/example-1.jpg",
        "instagramThumbnail": "https://pozy.ai/media/example-1.jpg",
        "subtitles": [
          {
            "url": "https://pozy.ai/media/example-1.jpg",
            "language": "en"
          }
        ],
        "tiktokProcessed": true
      }
    ],
    "platforms": [
      {
        "platform": "instagram",
        "accountId": "696e0b682d0a31188e7a2ba9",
        "customContent": "Hello from Pozy",
        "customMedia": [
          {
            "type": "image",
            "url": "https://pozy.ai/media/example-1.jpg",
            "fileId": "6035bf6bd3aac3067c336c50",
            "accountId": "696e0b682d0a31188e7a2ba9",
            "title": "Launch day",
            "altText": "Hello from Pozy",
            "filename": "photo.jpg",
            "size": 482133,
            "mimeType": "image/jpeg",
            "thumbnail": "https://pozy.ai/media/example-1.jpg",
            "instagramThumbnail": "https://pozy.ai/media/example-1.jpg",
            "subtitles": [
              {
                "url": "https://pozy.ai/media/example-1.jpg",
                "language": "en"
              }
            ],
            "tiktokProcessed": true
          }
        ],
        "scheduledFor": "2026-10-02T09:00:00.000Z",
        "platformSpecificData": {},
        "status": "active",
        "platformPostId": "637f799b3039e6602e83fa4f",
        "platformPostUrl": "https://pozy.ai/media/example-1.jpg",
        "publishedAt": "2026-10-02T09:00:00.000Z",
        "removedFromPlatformAt": "2026-10-02T09:00:00.000Z",
        "isTrialReel": true,
        "trialGraduationStrategy": "MANUAL",
        "publishAttempts": 1,
        "publishRetries": 1,
        "errorMessage": "Hello from Pozy",
        "errorCategory": "auth_expired",
        "errorSource": "user",
        "platformError": {
          "code": 1,
          "subcode": 1,
          "message": "Hello from Pozy"
        }
      }
    ],
    "scheduledFor": "2026-10-02T09:00:00.000Z",
    "timezone": "America/New_York",
    "status": "draft",
    "tags": [
      "string"
    ],
    "hashtags": [
      "string"
    ],
    "mentions": [
      "string"
    ],
    "visibility": "public",
    "metadata": {},
    "recycling": {
      "enabled": true,
      "gap": 1,
      "gapFreq": "week",
      "startDate": "2026-10-02T09:00:00.000Z",
      "expireCount": 42,
      "expireDate": "2026-10-02T09:00:00.000Z",
      "contentVariations": [
        "Hello from Pozy"
      ],
      "contentVariationIndex": 1,
      "recycleCount": 42,
      "nextRecycleAt": "2026-10-02T09:00:00.000Z",
      "lastRecycledAt": "2026-10-02T09:00:00.000Z"
    },
    "recycledFromPostId": "6786dd4f9a1815d922da3579",
    "queuedFromProfile": "string",
    "queueId": "6a5f84bc69bcee401578bb47",
    "createdAt": "2026-10-02T09:00:00.000Z",
    "updatedAt": "2026-10-02T09:00:00.000Z"
  },
  "warnings": [
    "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.
404	not_found	Nothing with that id exists in your workspace.
429	rate_limit_error	Too many requests this minute. Wait for `Retry-After` seconds.

Every code is listed in Errors.