From 307d583a664de2f030ad660942725204135fcd7a Mon Sep 17 00:00:00 2001
From: Gilad Resisi <giladresisi@gmail.com>
Date: Sun, 30 Aug 2026 11:23:47 +0700
Subject: [PATCH] docs(public-api): document thumbnailTimestamp on the media
 object

---
 public-api/openapi.json     |  4 ++++
 public-api/posts/create.mdx | 14 ++++++++++++++
 2 files changed, 18 insertions(+)

diff --git a/public-api/openapi.json b/public-api/openapi.json
index 21629023..511303c4 100644
--- a/public-api/openapi.json
+++ b/public-api/openapi.json
@@ -2574,6 +2574,10 @@
           },
           "path": {
             "type": "string"
+          },
+          "thumbnailTimestamp": {
+            "type": "number",
+            "description": "Milliseconds into the video to use as the cover/thumbnail frame. Supported by Instagram, Instagram Standalone, TikTok Business, and TikTok (Direct Post only, not the UPLOAD/inbox flow); other providers ignore it. For TikTok, in our testing the cover was applied only to public posts (privacy_level PUBLIC_TO_EVERYONE)."
           }
         }
       },
diff --git a/public-api/posts/create.mdx b/public-api/posts/create.mdx
index 2cabf1e4..8f78ba57 100644
--- a/public-api/posts/create.mdx
+++ b/public-api/posts/create.mdx
@@ -29,6 +29,20 @@ Before re-submitting, strip the server-managed fields from the fetched object, r
 
 Then set a fresh `type` (`now`, `schedule`, or `draft`) and `date`, and `POST` the cleaned object.
 
+## Video cover frame (`thumbnailTimestamp`)
+
+Each media object in a post's `image` array accepts an optional `thumbnailTimestamp` field: the number of milliseconds into the video to use as the cover/thumbnail frame.
+
+```json
+{
+  "image": [{ "id": "vid-123", "path": "https://uploads.postiz.com/video.mp4", "thumbnailTimestamp": 3000 }]
+}
+```
+
+Supported providers: Instagram, Instagram Standalone, TikTok Business, and TikTok (Direct Post only — the `UPLOAD`/inbox flow does not support cover selection). Other providers ignore the field.
+
+For TikTok, in our testing the cover was applied only to public posts (`privacy_level: "PUBLIC_TO_EVERYONE"`); posts published with a restricted privacy level kept the first frame as the cover.
+
 ## Provider-Specific Settings
 
 When creating posts, each social media platform requires different settings. The `settings` object must include a `__type` field that identifies the platform.