Փաստաթղթեր մշակողների համար
ViewTracker Publishing API
Publish and schedule social posts with a Postiz-compatible API contract. Includes migration instructions, platform settings and OpenAPI.
Այս նյութն առայժմ հասանելի է անգլերեն։ Նավարկումն ու հավելվածը հասանելի են ձեր ընտրած լեզվով։
Create drafts, enqueue posts, schedule publication and inspect each destination using the same connections, content checks and background publisher as the ViewTracker app.
Base URL: https://www.viewtracker.ai/api/public/v1
Download OpenAPI 3.1 for Postman or client generation. The tracking API and webhooks are separate.
Authentication and access
Connect accounts in Publish → Profiles & accounts and create a workspace API key in Settings. Raw-key Authorization matches Postiz. Bearer authentication also works.
export VIEWTRACKER_BASE_URL='https://www.viewtracker.ai/api/public/v1'
export VIEWTRACKER_API_KEY='vt_live_REPLACE_ME'
curl "$VIEWTRACKER_BASE_URL/integrations" \
-H "Authorization: $VIEWTRACKER_API_KEY"Keys belong to one workspace and cover all its publishing profiles; per-profile key scopes are unavailable. Keep them on your server. Revocation stops authenticated calls, but does not cancel scheduled posts. Reading requires Growth or higher; uploads, publication and cancellation require Ultra or higher and an active subscription. Publishing must also be enabled for the workspace. API access does not bypass provider app review, account authorization or the current rollout gate.
The shared limit is 120 requests per minute per key, including tracking and MCP calls. Throttled responses include Retry-After. Authenticated responses are not cached.
Migrate from Postiz
This implements the documented publishing subset, rather than the entire Postiz API.
- 1Connect the same social accounts to ViewTracker through the app. OAuth grants and tokens are not imported from Postiz.
- 2Create a ViewTracker API key and change the client's base URL and key.
- 3Fetch GET /integrations and update stored integration IDs. Profile/group, media and post IDs are service-specific too.
- 4Upload media to ViewTracker and use the returned media IDs.
- 5Check the platform settings and compatibility table below, then test your automation.
Before: https://api.postiz.com/public/v1
After: https://www.viewtracker.ai/api/public/v1
Authorization: <ViewTracker API key>A client that discovers channels and uploads media dynamically can keep the supported paths and JSON structure after this setup. Hard-coded Postiz IDs must change. Existing schedules remain in Postiz: changing a URL does not move or cancel them. Check or cancel the original before recreating a pending post to avoid publishing twice.
Checked against the official Postiz API reference and create-post schema on November 3, 2026. SDKs and n8n nodes that use unsupported endpoints, settings or Postiz OAuth tokens need changes; full interchangeability is not claimed.
Endpoints
All paths below are relative to the Publishing base URL.
| Method | Path | Result |
|---|---|---|
| GET | /is-connected | { "connected": true } after key, plan and Publishing checks |
| GET | /me | organization { id, name }, user: null |
| GET | /groups | Active publishing profiles as { id, name } |
| GET | /integrations | Authorized accounts; optional group profile filter |
| GET | /integration-settings/{id} | output.rules, maxLength, settings and tools: [] |
| GET | /posts | Destinations within required startDate and endDate; optional customer profile filter |
| POST | /posts | Draft, immediate or scheduled posts |
| DELETE | /posts/{id} | Cancel an unstarted group; retain history |
| DELETE | /posts/group/{group} | Same cancellation using the listed group ID |
| POST | /upload | One multipart file, up to 4 MiB |
| POST | /upload-from-url | Import public HTTPS media |
| GET | /media/{id}/status | Verify file availability; return ready |
| GET | /media | pages and results, 18 files per page |
| POST | /uploads/presign | ViewTracker extension: signed direct-upload PUT |
| POST | /uploads/complete | ViewTracker extension: verify and register the PUT |
An integration is a publishing destination, not a tracked analytics account. Facebook destinations are Pages. Instagram reports instagram-standalone; settings accept either instagram-standalone or instagram. Discovery never exposes social tokens.
One account can belong to several profiles. customer is the filtered or earliest active profile, and the groups extension lists all active memberships. The optional profileId on each post item selects one; otherwise the earliest active profile containing that account is used.
Create a post and first comment
The first value item is the root. A second item creates one text-only first comment or Threads reply, when the account's existing permission grant allows it. No new permission is requested through this endpoint. YouTube first comments are unavailable.
curl -X POST "$VIEWTRACKER_BASE_URL/posts" \
-H "Authorization: $VIEWTRACKER_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: release-2026-11-03-threads-1" \
-d '{
"type": "now", "shortLink": false, "tags": [],
"posts": [{
"integration": { "id": "pcn_FROM_INTEGRATIONS" },
"value": [
{ "content": "Our new release is here.", "image": [] },
{ "content": "More at https://example.com/release", "image": [] }
],
"settings": { "__type": "threads" }
}]
}'[{ "postId": "ptg_EXAMPLE", "integration": "pcn_FROM_INTEGRATIONS" }]Acceptance means queued, not published. The background worker normally begins within a minute; provider media processing can take longer. Use GET /posts to inspect outcomes. A first comment has its own result; its failure does not undo a successful root post.
Drafts, scheduling and idempotency
type now ignores date and queues immediately. type draft stores without publishing. type schedule requires date in ISO 8601 with an explicit UTC offset, at least one minute ahead and within 60 days. Each item may have different content, media and settings. Up to 12 items share the request intent/date and commit atomically; a failed validation or final write creates none of them.
Send a unique Idempotency-Key for each intended batch. Retrying the same parsed payload returns the same destination IDs, including after publication. Reusing it with changed content returns 409. JSON object-key ordering does not matter; post ordering does. An edit to the original post can also return 409 and should be inspected. Without this header, repeating POST creates another batch.
Use shortLink: false and tags: [], or omit them. Link shortening, top-level tagging, recurring intervals, supplied group IDs, editing through nested post IDs and arbitrary reply chains are unavailable. Unknown fields fail validation. Content is plain text; rich-text HTML is not converted.
Media uploads
JPEG/PNG images: up to 8 MiB. MP4/MOV videos: up to 500 MiB. Instagram requires JPEG images; PNG is not converted automatically. Media must meet the destination's encoding, duration, dimensions and aspect-ratio rules.
For a file up to 4 MiB:
curl -X POST "$VIEWTRACKER_BASE_URL/upload" \
-H "Authorization: $VIEWTRACKER_API_KEY" \
-F 'file=@photo.jpg' -F 'adjust=false'For a larger file on a public server:
curl -X POST "$VIEWTRACKER_BASE_URL/upload-from-url" \
-H "Authorization: $VIEWTRACKER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/original.mp4","adjust":false}'The source must provide HTTPS, a supported Content-Type and positive Content-Length. Private, loopback, internal and metadata addresses are blocked, including redirect targets. The API key is never forwarded to the source. Imports are streamed with byte and time bounds. adjust=true and automatic transcoding are unsupported.
For authenticated sources, chunked downloads or local large files:
- 1POST /uploads/presign with name, size in bytes and type. Example: { "name": "clip.mp4", "size": 10485760, "type": "video/mp4" }.
- 2PUT the bytes to the returned url with the returned headers. Do not send your ViewTracker API key to storage.
- 3POST /uploads/complete with { "id": "ID_FROM_PRESIGN" }.
- 4Use the returned id and path in the root item's image array, including for video.
{
"integration": { "id": "pcn_INSTAGRAM" },
"value": [{
"content": "A look at our new release.",
"image": [{ "id": "pmd_EXAMPLE.jpg", "path": "URL_FROM_UPLOAD" }]
}],
"settings": { "__type": "instagram-standalone", "post_type": "post" }
}An upload response includes id, name, path, organizationId, createdAt, updatedAt and status ready. id is the authoritative ViewTracker reference; path is a preview URL valid for one hour. It is not fetched from the caller when posting. Scheduling generates fresh delivery links at execution. Old Postiz media IDs cannot be reused.
Files are temporary publishing assets. Unattached uploads are protected for at least seven days. Drafts and pending posts protect referenced files, subject to the bucket's 90-day lifecycle. After all destinations finish, normal cleanup uses the seven-day retry window. Scheduling verifies enough media lifetime remains. This is not permanent archival storage.
GET /media?page=1 returns pages and results. Names use storage IDs; original-name search is unavailable. GET /media/{id}/status checks actual object availability. Missing or expired media must be uploaded again.
Platform settings and formats
Match settings.__type to the authorized account. Unsupported choices return 422 before scheduling.
| Platform | Settings | Formats |
|---|---|---|
| __type: facebook; optional title for video | Text, photo, image carousel, video, Reel, Story | |
| __type: instagram or instagram-standalone; post_type: post, reel or story; optional share_to_feed | JPEG photo, supported carousel, video/Reel, Story | |
| Telegram | __type: telegram; optional message_thread_id, disable_notification, protect_content | Text, photo, MP4 video, mixed-media album |
| Threads | __type: threads | Text, photo, supported carousel, video |
| YouTube | __type: youtube; title; type: private, unlisted or public | One video |
| TikTok | __type: tiktok; content_posting_method: UPLOAD; optional title | One video delivered to Inbox |
YouTube also accepts selfDeclaredMadeForKids: yes/no and tags [{ value, label? }], at most 30 tags and 450 combined characters including separators.
Format is inferred: no media → text, one image → photo, several files → carousel, one Instagram video → reel, other single videos → video. The optional format extension explicitly selects text, photo, carousel, video, reel or story. Use format: reel for a Facebook Reel. Normal platform/format checks still apply, including carousel limitations.
Instagram is_trial_reel may be false and collaborators may be empty. Trial Reels, collaborators, alt text, cover-frame/music selection, custom thumbnails, delayed comments and Facebook link-preview/background settings are unavailable.
TikTok Direct Post requires the composer's interactive creator choices and consent; this API exposes only UPLOAD. Inbox delivery is not public publication. Privacy, duet, stitch, comment, music and disclosure settings have no effect in UPLOAD mode and are finalized in TikTok, matching Postiz's Inbox behavior.
Instagram and Facebook Stories
Use settings.post_type: story for Facebook or Instagram, or the format: story extension. One image or video creates one Story; upload a finished file with any desired text already embedded. Root content must be empty, and first comments are unavailable. Captions are rejected rather than silently omitted. The editor has the same Story format and supports drafts and schedules.
The ViewTracker limits are one file, videos up to 100 MB and 3–60 seconds, Facebook images up to 4 MiB, and Instagram JPEG images up to 8 MiB. The editor checks available duration metadata; Meta validates the actual media encoding and duration. A vertical 9:16 canvas is recommended. Story eligibility depends on Meta and the connected professional account; some Instagram login/account configurations require a Business account.
Stories expire on the social platform after 24 hours. They are retained in ViewTracker history with their publication result, but do not enter video tracking. Meta may not return a usable permalink; a missing link is not an error after a confirmed publication. Music, polls, link stickers and other interactive overlays are not added automatically. Prepare overlays in your media or add them natively.
{
"type": "schedule",
"date": "2026-11-10T10:00:00Z",
"posts": [{
"integration": { "id": "pcn_INSTAGRAM" },
"value": [{ "content": "", "image": [{ "id": "pmd_EXAMPLE.jpg", "path": "URL_FROM_UPLOAD" }] }],
"settings": { "__type": "instagram-standalone", "post_type": "story" }
}]
}History and cancellation
GET /posts requires startDate and endDate, at most 93 days apart. customer filters by publishing profile. More than 1000 matching destinations returns 422; split the date range rather than assuming partial results are complete.
curl "$VIEWTRACKER_BASE_URL/posts?startDate=2026-11-01T00:00:00Z&endDate=2026-11-30T23:59:59Z" \
-H "Authorization: $VIEWTRACKER_API_KEY"The posts array has one entry per destination: id, group, content, publishDate, releaseURL, releaseId, integration, image, settings, state and error. ViewTracker adds the precise status and separate firstComment result. Compatibility states are DRAFT, QUEUE, PUBLISHED and ERROR. TikTok Inbox delivery has terminal status in_drafts and compatibility state QUEUE because it is not publicly published; do not wait for a public URL. A failed comment appears separately even when the root is PUBLISHED.
DELETE uses the returned destination postId, or group from listing. Both paths cancel all unstarted destinations in the parent post. Canceled entries disappear from API lists but remain in app history. Repeating cancellation is safe. Processing, published, failed or remotely initialized posts return 409. No published content is deleted from the social network.
Compatibility boundaries
| Postiz feature | ViewTracker |
|---|---|
| Raw-key Authorization | Supported with a ViewTracker key; Bearer also accepted |
| Integrations and groups | Supported; groups map to publishing profiles |
| now, draft, schedule, per-channel content | Supported for the platforms listed above |
| One first comment/reply | Supported where the existing account grant permits it |
| Multipart upload | Same path/form; 4 MiB limit here |
| URL upload | Same path/JSON; supported MIME and Content-Length required |
| Media adjustment or name search | Unavailable |
| Delete | Cancels unstarted delivery, preserves history, no remote deletion |
| TikTok Direct Post | Interactive composer only |
| OAuth apps, channel-connect API, provider tools | Unavailable; connect in the app |
| Slot discovery, status/settings updates, release-ID repair | Unavailable; use the editor and queue |
| Postiz analytics/notifications | Unavailable; ViewTracker tracking API is separate |
| Other platforms, AI generation and clipping | Unavailable in this Publishing API |
Recognized unimplemented Postiz endpoint families return 501; unknown paths return 404. Migration does not change any provider's app-review status.
Errors and retry behavior
Errors are JSON { "error": "message" }, with a docs link for Publishing-specific failures.
| Status | Meaning |
|---|---|
| 400 | Invalid JSON, unknown fields or malformed request |
| 401 | Missing, invalid or revoked ViewTracker key |
| 402 | Inactive subscription |
| 403 | Plan or Publishing rollout does not permit access |
| 404 | Resource not found in this workspace, or unknown path |
| 409 | Idempotency conflict, edited post or publication started |
| 413 | Body or file exceeds its limit |
| 422 | Unsupported settings or failed content, date or media checks |
| 429 | Shared key rate limit; observe Retry-After |
| 501 | Recognized Postiz endpoint is not implemented |
| 502/503 | Temporary upstream storage, database or service failure |
JSON bodies are limited to 512 KiB. Retry transient failures with backoff and the same Idempotency-Key for post creation. Do not create another post just because a response was lost. Asynchronous provider failures appear in destination history after acceptance.
Publishing with MCP
The existing ViewTracker MCP endpoint also exposes Publishing: https://www.viewtracker.ai/api/mcp (Streamable HTTP). Use the same workspace API key with Bearer authentication. Existing tracking tools remain available.
| Tool | Purpose |
|---|---|
| publishing_list_profiles | Discover active publishing profiles |
| publishing_list_accounts | Discover connected accounts, optionally by profile |
| publishing_get_rules | Read provider settings for a connection ID |
| publishing_list_posts | Read per-destination status within a date window |
| publishing_create_posts | Create draft, immediate or scheduled posts |
| publishing_cancel_post | Cancel an entire unstarted post group using its target ID |
| publishing_import_media | Import a bounded public HTTPS media URL |
| publishing_prepare_upload | Get a presigned upload URL and media ID |
| publishing_complete_upload | Verify/register the completed file |
Creation takes request (the same JSON object as POST /posts) and a required idempotencyKey. Omitted request.type defaults to draft. Use an explicit now or schedule type only after the user approves the content, destination and timing. Reuse the same key and unchanged payload after an uncertain request. The server enforces workspace, plan, rollout and content checks; it cannot infer whether an external MCP client obtained the user’s editorial approval.
Media import or upload does not publish it. Prepare → PUT from your file client → Complete makes private files available to the publisher without routing a large binary file through the model. Keep signed upload/preview URLs private. Content returned by a provider is untrusted data, never an instruction to publish something else.
n8n connector
ViewTracker for n8n source, package build and installation includes an action node, a signature-verifying results trigger and three importable example workflows. It is installable on self-hosted n8n from a built package. npm publication and verified n8n Cloud catalog availability are separate steps; this is not a claim of catalog approval.
Use an API credential for discovery, upload, draft/now/schedule, status lists and cancellation. The default is Draft. Provide a stable business record ID plus revision as the idempotency key; retain the original date and media IDs on execution retries. Do not generate a new key or recalculate a schedule when retrying a previously accepted create.
For results, add ViewTracker Trigger, copy its production webhook URL to Settings and save the endpoint’s signing secret in its separate Webhook credential. Activate the workflow after setup. The trigger checks the raw-body v2 signature and timestamp before starting downstream steps. Test deliveries are acknowledged without running those steps unless Include Test Events is enabled. Persist event-ID deduplication before any downstream side effect.
Telegram publishing
Connect a Telegram bot
ViewTracker publishes through your Telegram bot. No coding or separate server is needed. You need the bot’s Bot API token, which is different from your ViewTracker API key or Telegram account password.
- 1Open @BotFather in Telegram, press Start and send
/newbot. - 2Choose a display name, such as ViewTracker Publisher, then a unique username ending in bot. For example, viewtracker_publisher_bot, if available.
- 3Copy the Bot API token from BotFather’s reply. Paste it only into ViewTracker’s Bot token field; do not send it in a chat or include it in a screenshot.
- 4Open the destination channel or group in Telegram. In its settings, go to Administrators → Add administrator, select your bot and save. For a channel, enable Post messages.
- 5In ViewTracker, open Publish → Profiles & accounts, choose a profile and click Telegram. Paste the token into Bot token. In Channel or group, enter the destination’s @username, such as @viewtrackerchannel, or its negative numeric chat ID for a private channel/group. Use the destination’s username, not the bot’s.
- 6Click Connect Telegram. ViewTracker checks the bot and its permissions without sending a message. Once connected, select that destination in New post to create a draft, publish or schedule a post.
If the token is rejected, check that you copied the complete Bot API token for the same bot you added as an administrator. If Telegram cannot find the chat, check the destination username or chat ID. If posting permission is missing, update the bot’s administrator permissions in Telegram and try connecting again.
See Telegram’s official bot creation guide for more about obtaining a token.
Connection and supported formats
Connection uses getMe/getChat/getChatMember, sends no message, and does not replace the bot’s existing update webhook. Tokens are encrypted using the existing publishing token key. Personal chats and Telegram Stories are outside this connector.
Telegram supports plain text (up to 4,096 UTF-16 units), one photo, an MP4 video, or an album of 2–10 photos/videos. Media captions support 1,024 units. This version sends signed media URLs to the official Bot API, so photos are limited to 5 MB and videos to 20 MB. This is different from Telegram’s larger multipart upload limits. Photos must also satisfy Telegram’s dimension/aspect limits. Formatting markup is sent literally; parse_mode and first comments are not supported.
Provider settings example:
{
"__type": "telegram",
"message_thread_id": 77,
"disable_notification": true,
"protect_content": false
}message_thread_id is optional and only available for connected forum supergroups. Omit it for a normal channel/group or the General topic. Check the topic ID yourself; Bot API has no read-only method to verify that an arbitrary existing topic is open. Invalid topics fail with a visible error, rather than silently posting to another topic. Reconnect a group after enabling forum mode to refresh its connection capabilities.
A successful send records Telegram’s message ID. Public usernames produce a t.me permalink; private chats can have no public link. Telegram view tracking is not included. A timeout or ambiguous server failure is marked for manual checking and is not automatically sent again. Confirmed 429 rejections use retry_after; invalid/revoked access requires reconnecting. Remove the bot from the chat or revoke its token in @BotFather to end its Telegram access outside ViewTracker.
Publishing events
In Settings → Outbound webhooks, subscribe an endpoint to the results you need. Existing endpoints keep video.updated only until explicitly changed. Outbound events require an active Ultra or higher API-write plan.
| Event | Meaning |
|---|---|
| publishing.published | One destination confirmed publication |
| publishing.in_drafts | TikTok confirmed Inbox delivery; not a public post |
| publishing.failed | One destination stopped after a permanent error or exhausted retries |
| video.updated | Existing tracked-video metrics event |
Each destination produces its own result. No final-failure event is sent for a temporary publishing retry. A failed delivery to your endpoint never causes the social post to be sent again. First comments run separately; inspect firstCommentStatus or authenticated post history for their final result.
{
"id": "evt_example",
"event": "publishing.published",
"createdAt": "2026-11-03T12:00:00.000Z",
"data": {
"postId": "pst_example",
"targetId": "ptg_example",
"integrationId": "pcn_example",
"profileId": "ppf_example",
"platform": "telegram",
"account": "@example_channel",
"status": "published",
"externalPostId": "42",
"postUrl": "https://t.me/example_channel/42",
"publishedAt": "2026-11-03T12:00:00.000Z",
"error": null,
"firstCommentStatus": "none"
}
}The result and its pending deliveries are committed atomically. Delivery runs from the maintenance queue, recovers abandoned attempts, and tries up to five times with at least one minute between attempts. Successful endpoints are not deliberately replayed, but a lost acknowledgment can still cause duplicates: delivery is at-least-once. Deduplicate by the stable body.id in a durable unique store before a downstream side effect. There is no ordering guarantee across endpoints/destinations and no automatic redelivery after the five-attempt limit.
Verify x-viewtracker-signature-v2 using HMAC-SHA256 over timestamp + "." + rawBody, compare in constant time, and reject timestamps more than five minutes from your clock. The Unix timestamp is in x-viewtracker-timestamp; the event name is also in x-viewtracker-event. The legacy x-viewtracker-signature (body-only HMAC) is retained, but v2 is recommended. See the signature verifier and examples. Do not reserialize JSON before verification. Test deliveries include test: true and use the endpoint’s first selected event. Provider tokens, full captions and signed media URLs are omitted from publication-result payloads.