docs(public-api): document per-post analytics caveats and TikTok interim release values

[giladresisi]

⚠️ Do not merge until gitroomhq/postiz-app#2007 is deployed

This PR describes the app's behaviour after that deployment: the lazy resolution of the TikTok video ID on the first per-post analytics request does not exist in production yet.

What

Adds prose to the Post Analytics API page: which platforms return data (linking to the per-post list in the Analytics guide) and why the endpoint returns an empty array (platform without per-post metrics, post without a platform ID, or a TikTok post whose video ID is not resolved yet). Tightens the operation description in openapi.json accordingly.

Adds releaseId to the Post schema returned by GET /posts (it was already returned but undocumented) and documents the TikTok interim values on releaseId and releaseURL: until the video ID is resolved they hold TikTok's publish handle and the channel's profile URL.

Why

A customer using the public API reported that per-post analytics returned an empty array for their TikTok posts, and that the posts' releaseURL pointed at their profile rather than the video. Nothing in the docs explained either. TikTok only exposes the public video ID after its moderation pass, which can outlast the ~100 seconds Postiz polls after publishing, so the interim publish handle and profile URL were stored and per-post analytics stayed empty. With gitroomhq/postiz-app#2007 Postiz resolves the ID lazily on the next per-post analytics request; until then the interim values remain, and this needs to be visible in the API docs.

The same customer's third complaint, the docs sending them in a loop when asking which platforms have per-post metrics, is handled in #245.

Depends on #245 for the /general/analytics#per-post-metrics anchor (text dependency only, the branch is not stacked on it).

Testing

Rendered the Post Analytics and List Posts pages locally with mint dev in a real browser: the new sections, the operation description and the releaseId / releaseURL field docs render correctly with no overflow. node scripts/check-prose.mjs --changed passes; node scripts/check-docs.mjs --changed reports only the anchor that lands with #245.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Roikk7Asuuix92LqWmpNop

[postiz-agent]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[coderabbitai]

Warning

Review limit reached

Next included review available in 53 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 5059994f-282e-49c2-a4b2-4c0fed78379d

📥 Commits

Reviewing files that changed from the base of the PR and between 227f80e and 3fa332b.

📒 Files selected for processing (2)

• public-api/analytics/post.mdx
• public-api/openapi.json

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}