addInboxMessageReaction
ChatGPTReact to a message — Adds the Page's reaction to one message in a Facebook Messenger thread, replacing any reaction it already had there. The stored message then lists it in reactions with fromMe: true. Facebook Pages only: an Instagram conversation answers 400 unsupported. Needs the Page's messaging scope. Limited to 300 reaction changes per hour per user, shared with removing reactions. Requires a read-write API key.
bulkCreateContacts
ChatGPTBulk create contacts — Requires read_write. Limited to 20 imports/hour/user. Runs as one mutation. Processes 1–1000 rows with individual errors; duplicate channel or profile email skips the row and merges only tags. Remaining rows fail once the contact cap is reached. platform is ignored with accountId and rejected without it. Envelope profile/account errors fail the request.
createConnectUrl
ChatGPTCreate an OAuth connect URL — Initiates an OAuth connection flow and returns an authorization URL to redirect the user to. The OAuth state expires after 10 minutes. This endpoint requires a read-write API key. For bluesky, the returned authUrl is a PostZen-hosted page where the user enters their Bluesky handle and app password (no developer app or OAuth redirect is required); the connection completes when they submit that form. For telegram, the returned authUrl is a PostZen-hosted page that issues a short-lived access code (there is no OAuth grant and no Telegram authorization screen); the connection completes when the user adds @PostZenScheduleBot as an administrator of a channel or group and sends that code to the bot. Complete sign-in and authorization in the browser. Never request passwords, tokens, or authorization codes in chat. Verify completion with listAccounts.
createContact
ChatGPTCreate a contact — Requires read_write. Limited to 600 creates/hour/user. Creates a contact and optionally its first channel. Maximum 5000 contacts per user and 20 channels per contact. Unknown accounts return 404 accountNotFound; accounts in another profile or platform mismatches return 400 validation. Out-of-scope profiles return 403 forbidden.
createMediaPresign
ChatGPTCreate a presigned media upload URL — Creates a presigned URL for uploading an image, video, GIF, or PDF to PostZen-hosted storage. Upload the file with an HTTP PUT to uploadUrl, then reference publicUrl in post mediaItems. This endpoint requires a read-write API key.
createPinterestBoard
ChatGPTCreate Pinterest board — Creates a board for the connected Pinterest account. This endpoint requires a read-write API key.
createPost
ChatGPTCreate a post — Creates a draft, scheduled post, immediate post, or queued post. This endpoint requires a read-write API key. Provide exactly one creation mode: publishNow, scheduledFor, isDraft, or queuedFromProfile (optionally with queueId), which claims the next free slot in that profile's queue and returns it as scheduledFor. The accounts in platforms can belong to different profiles; an API key limited to selected profiles must have access to the profile of every account.
createProfile
ChatGPTCreate a profile — Creates a profile. This endpoint requires a read-write API key with access to all profiles.
createQueue
ChatGPTCreate a queue — Creates a posting queue on a profile. A profile may hold up to 10 queues, each with up to 56 slots. The first queue on a profile automatically becomes its default. This endpoint requires a read-write API key.
createWebhook
ChatGPTCreate a webhook — Creates an outbound webhook endpoint. A user may have up to 25 endpoints. This endpoint requires a read-write API key. Signing secrets and authentication headers can only be configured in the PostZen dashboard. Never request them in chat.
deleteContact
ChatGPTDelete a contact — Requires read_write. Limited to 300 deletes/hour/user. Atomically deletes the contact and all its channels (maximum 20). Unknown or out-of-scope ids return 404 contactNotFound.
deletePost
ChatGPTDelete a post — Deletes a draft, scheduled, queued, failed, partially failed, or canceled post. Published and publishing posts cannot be deleted.
deleteProfile
ChatGPTDelete a profile — Deletes a profile. The default profile cannot be deleted, and profiles with connected accounts must be disconnected first.
deleteQueue
ChatGPTDelete a queue — Deletes the queue named by queueId, or every queue on the profile when queueId is omitted. Posts already placed by the queue keep their scheduled times; only the queue link is removed. Deleting the default queue promotes the profile's oldest remaining queue. This endpoint requires a read-write API key.
deleteWebhook
ChatGPTDelete a webhook — Deletes an endpoint and stops new event fan-out. Retained delivery logs remain available until their retention period ends.
disconnectAccount
ChatGPTDisconnect an account — Disconnects and removes a connected social account. Pending scheduled, queued, and publishing targets for that account are canceled. This endpoint requires a read-write API key.
getAccountInsights
ChatGPTGet account insights — Daily profile activity and audience for a TikTok account connected through the TikTok Business app. Other accounts return 400 with code platformUnsupported.
getAnalytics
ChatGPTGet post analytics — Returns one post when postId is supplied. Otherwise returns a paginated analytics list with aggregate overview metrics.
getBestTimeToPost
ChatGPTGet the best times to post — Returns historical engagement slots grouped by UTC day of week and hour, ordered by average engagement descending. Hours are UTC; day_of_week uses 0 = Sunday through 6 = Saturday.
getContact
ChatGPTGet a contact — Requires read_only. Returns the contact with distinct conversationIds and channels, oldest first. Unknown or out-of-scope ids return 404 contactNotFound. Counters start when Contacts ships; history is not backfilled.
getContactChannels
ChatGPTGet contact channels — Requires read_only. Returns all channels oldest first by createdAt, including lastActiveAt. Unknown or out-of-scope contacts return 404 contactNotFound.
getDailyMetrics
ChatGPTGet daily analytics metrics — Returns daily aggregate metrics and a per-platform breakdown. Publish attribution assigns lifetime metrics to the post's publish date; received attribution assigns metric deltas to the day they were observed.
getFollowerStats
ChatGPTGet follower statistics — Returns follower history and growth for connected accounts at daily, weekly, or monthly granularity.
getInboxConversation
ChatGPTGet a direct message conversation — Returns one thread, refreshing PostZen’s stored copy from the platform first. Read-only and read-write API keys are accepted. This operation may update PostZen’s persisted inbox copy while retrieving data; it does not send messages or mark them read.
getNextQueueSlot
ChatGPTGet the next queue slot — Returns the next free instant the queue would hand out. This is a preview only — the slot is not reserved. Create queued posts with queuedFromProfile rather than passing this value back as scheduledFor, or a concurrent create can take the slot first.
getPinterestBoards
ChatGPTList Pinterest boards — Lists boards owned by a connected Pinterest account. Read-only and read-write API keys are accepted.
getPost
ChatGPTGet a post — Returns one post when the API key can access the profile of every account the post targets. Missing and inaccessible posts both return 404.
getPostTimeline
ChatGPTGet a post analytics timeline — Returns one daily row per platform for a PostZen post, imported external post, or platform post id.
getProfile
ChatGPTGet a profile — Returns a single profile visible to the API key.
getWebhook
ChatGPTGet a webhook — Returns one webhook endpoint visible to the API key without secret or custom header values.
listAccounts
ChatGPTList accounts — Returns connected social accounts available to the API key, sorted by connection date (newest first). Read-only and read-write API keys are accepted.
listContacts
ChatGPTList contacts — Returns contacts in the API key scope, newest first. Requires read_only. Search matches name, email or company. Tag filters use any match. Account and platform filters use contact channels. filters.tags always covers the unfiltered in-scope set. Reads use the plan per-minute budget.
listInboxConversationMessages
ChatGPTList messages in a conversation — Returns the messages PostZen holds for one thread, oldest first by default, refreshing them from the platform when the stored copy is stale. It never marks the thread read — use POST /v1/inbox/conversations/{conversationId}/read for that. Meta returns full content only for roughly the twenty newest Instagram messages, so older ones may carry an id and timestamp without text or attachments. Read-only and read-write API keys are accepted. This operation may update PostZen’s persisted inbox copy while retrieving data; it does not send messages or mark them read.
listInboxConversations
ChatGPTList direct message conversations — Returns the Instagram direct message threads PostZen holds for the accounts this key can reach, newest activity first, and refreshes that stored copy from the platform as a side effect (throttled per account, so a tight polling loop costs nothing extra). meta reports which accounts could not be refreshed; their stored threads are still returned. Read-only and read-write API keys are accepted. This operation may update PostZen’s persisted inbox copy while retrieving data; it does not send messages or mark them read.
listPinterestBoardsForSelection
ChatGPTList Pinterest boards for the connect flow — Lists boards after Pinterest OAuth completes so the client can show a board picker. The state handle remains valid for board selection for 30 minutes from connect-flow creation. This endpoint requires a read-write API key.
listPosts
ChatGPTList posts — Returns posts the API key can access, newest first. A post's profiles are the profiles of its target accounts, and a key limited to selected profiles only sees posts whose accounts all sit in profiles it can access. Read-only and read-write API keys are accepted. Published posts include a platformPostId and platformPostUrl for each published platform target. Results are capped to the 1000 most recent matching posts.
listProfiles
ChatGPTList profiles — Returns profiles available to the API key, sorted by creation date (oldest first). Read-only and read-write API keys are accepted.
listQueueSlots
ChatGPTGet a queue schedule — Returns the queue selected by queueId, or the profile's default queue when queueId is omitted. With all=true every queue on the profile is returned instead. nextSlots holds the next five instants the queue would hand out, already skipping occupied slots; a paused or slotless queue returns an empty array.
listWebhookDeliveries
ChatGPTList webhook deliveries — Returns retained delivery logs visible to the API key, newest first. Results are capped to the 1000 most recent matching deliveries.
listWebhooks
ChatGPTList webhooks — Returns webhook endpoints visible to the API key, newest first. Secret and custom header values are never returned.
markInboxConversationRead
ChatGPTMark a conversation read — Moves the thread’s local read watermark to its newest synced message and returns how many incoming messages crossed from unread to read. Nothing is sent to the platform, and reading messages never does this implicitly. Requires a read-write API key.
previewQueue
ChatGPTPreview upcoming queue slots — Returns the next count instants the queue would hand out, in ascending order. Occupied slots are skipped, so the preview matches what the next posts would actually receive. Previewing reserves nothing.
redeliverWebhookDelivery
ChatGPTRedeliver a webhook event — Queues a new six-attempt delivery run on the retained delivery record while preserving its event id and attempt history. The endpoint must still exist and be active, and the delivery must not already be in progress.
removeInboxMessageReaction
ChatGPTRemove a reaction from a message — Removes the Page's own reaction from one message in a Facebook Messenger thread. The other participant's reaction is not affected. Facebook Pages only: an Instagram conversation answers 400 unsupported. Needs the Page's messaging scope. Limited to 300 reaction changes per hour per user, shared with adding reactions. Requires a read-write API key.
replyToInboxPost
ChatGPTComment on a post or reply to a comment — Publishes a comment on the post, or a reply to commentId when one is given. Requires a read-write API key and the account's comment-management scope; without the scope the call answers 403 platformCapabilityMissing and nothing is sent to the platform. attachmentUrl is Facebook only — every other platform rejects it with 400 attachmentUnsupported. Instagram is two levels deep, so replying to a reply is redirected to that reply's top-level parent. A Threads reply is created as a container and then published; when the publish is still pending after PostZen's internal retries the call returns 502 publishPending and the reply may still appear on its own, so check the thread before retrying rather than posting twice.
searchInboxConversations
ChatGPTSearch direct message conversations — Searches the conversations PostZen has already synced — Meta exposes no message search API, so this reads PostZen's own copy and refreshes it first. Message text matches whole tokens, case- and accent-insensitively (cafe finds café, art does not match start); participant names and usernames match on substring. Setting direction narrows the search to message text only, so a thread that matched only on the participant's name is excluded. Read-only and read-write API keys are accepted. This operation may update PostZen’s persisted inbox copy while retrieving data; it does not send messages or mark them read.
selectPinterestBoard
ChatGPTSelect Pinterest board — Verifies and stores the default board for the Pinterest account created by the connect session. This endpoint requires a read-write API key.
sendInboxMessage
ChatGPTSend a direct message — Sends a message into an existing thread. The recipient is the other participant on that thread, so no recipient id is needed. Exactly one of message or attachmentUrl may be sent per call — Meta's Send API carries one payload at a time, so combining them is a 400. Meta only accepts replies within 24 hours of the person's last message; outside that window the platform refuses the send and PostZen reports 400 PLATFORM_LIMITATION with Meta's own envelope attached. Sends are hard-gated on the account's messaging scope. Requires a read-write API key.
sendInboxTypingIndicator
ChatGPTShow a typing indicator — Shows the typing bubble to the other participant of a Facebook Messenger thread. Meta clears it on its own after 20 seconds or when your next message arrives, so call it again while a reply is still being written. Facebook Pages only: an Instagram conversation answers 400 unsupported. Once the conversation resolves the answer is always a 200; success is false when Meta declined the indicator, and there is nothing to retry. Needs the Page's messaging scope. Limited to 600 per hour per user. Requires a read-write API key.
syncExternalPosts
ChatGPTSynchronize external posts — Fetches an account's latest posts published directly on its platform. Supplying url or postId searches for a specific post. Requests made within the per-account debounce window return cached results with synced.skipped set to true.
testWebhook
ChatGPTTest a webhook — Queues a webhook.test event through the normal delivery pipeline using the endpoint's current URL, secret, and custom headers. The endpoint must be active.
updateContact
ChatGPTUpdate a contact — Requires read_write. Limited to 600 updates/hour/user. Supports partial updates, null clears for email, company, avatarUrl, notes and customFields, and [] to clear tags. customFields replaces the entire object. profileId and channel fields cannot be changed. Unknown or out-of-scope ids return 404 contactNotFound.
updateInboxConversation
ChatGPTArchive or unarchive a conversation — Sets the thread’s status. This is PostZen-local state — Meta has no archive API, so nothing is sent to the platform and a later sync never overwrites it. Requires a read-write API key.
updatePinterestBoards
ChatGPTSet default Pinterest board — Verifies a Pinterest board and stores it as the account default used when a pin target omits settings.boardId. This endpoint requires a read-write API key.
updatePost
ChatGPTUpdate a post — Updates an editable post. Every body field is optional; omitted fields keep their current values, and omitting all timing fields keeps the current scheduling and draft status. At most one of publishNow, scheduledFor, isDraft, or queuedFromProfile may select a new timing mode. Accounts in platforms can belong to different profiles; the API key needs access to all of them.
updateProfile
ChatGPTUpdate a profile — Updates one or more profile fields. This endpoint requires a read-write API key.
updateQueue
ChatGPTUpdate a queue — Replaces a queue's timezone and slots, and optionally renames, pauses, or promotes it to default. With reshuffleExisting: true the queue's future scheduled posts are re-placed onto the new schedule in their existing order; posts that are already publishing, published, or failed are never moved, and at most 200 posts may move in one call. Validation and slot assignment both run before the first write, so a rejected update leaves the queue untouched. This endpoint requires a read-write API key.
updateWebhook
ChatGPTUpdate a webhook — Updates one or more endpoint settings. Omitted fields are unchanged. This endpoint requires a read-write API key. Signing secrets and authentication headers can only be configured in the PostZen dashboard. Never request them in chat.
verifyApiKey
ChatGPTCheck that the configured PostZen API key is valid. Returns the number of profiles the key can access.