Stav na ViralShaker
REST API a MCP server pro tvoje vlastní nástroje a AI asistenty.
Getting started
The ViralShaker API lets your own tools and AI agents do everything you do in the app: brand profile, ideas and launching, every content format including AI video, AI Studio, AI influencers, Inspiration, media, scheduling, campaigns, analytics, billing links and team. Base URL: https://viralshaker.com/api/v1/public. A few things stay with people (approving drafts, managing keys, paying, connecting social accounts in a browser, deleting a workspace); for those the API returns a link to hand over.
Authentication
Create a key in Settings → API (any paid plan) and send it as a bearer token:
curl https://viralshaker.com/api/v1/public/workspaces/current \
-H "Authorization: Bearer $VIRALSHAKER_API_KEY"
AI agents can also sign in with OAuth instead of a key: add https://viralshaker.com/mcp as a connector and approve it on the consent page (see Agents and MCP). An OAuth connection covers every workspace you own or administer on a paid plan; send POST /workspaces/{id}/switch to move it (GET /workspaces lists them).
A key belongs to one workspace and acts with the permissions of the person who created it, limited to its scopes:
| Scope | Allows |
|---|---|
content:read |
content, media, audio, angles, Mixer preferences |
content:write |
create, edit, regenerate and delete content and angles |
launch:write |
launch content from the Mixer |
media:write |
upload and manage media |
characters:read |
AI influencers |
posts:read |
accounts, posts, campaigns, analytics |
posts:write |
schedule, edit and cancel posts, run and edit campaigns, connect and disconnect accounts |
brand:write |
edit the brand profile, re-analyse the website, finish onboarding |
studio:write |
generate AI videos (AI formats, Character Swap), AI Studio images and animations, product images (spends credits) |
crew:write |
create and edit AI influencers (spends credits) |
account:read |
plan, credits, usage, invoices, notifications, team |
account:write |
checkout and top-up links, notifications |
team:write |
invite, change and remove members (off unless you tick it) |
Safety for agents
Every key and connected app has:
- Review first (on by default for new keys): posts it schedules become drafts that wait for a person to approve them on the calendar or the preview page. The schedule response says
"reviewRequired": trueand includes apreviewUrl. - Max posts a day (default 10): more returns
429 agent_post_cap_reached. - Max credits a day (default 300): more returns
402 agent_credit_cap_reached.
Change these per key or app on the Agents page, where Pause all agents also stops every key and app from changing anything (403 agents_paused; reads still work). Calls that spend credits also accept an X-Max-Credits header: if the price is higher, the call is refused with 402 credit_limit_exceeded and details.estimate, and nothing is spent.
Conventions
- JSON in and out, camelCase fields. Successful responses are
{"data": …}; lists add{"pagination": {"cursor", "hasMore"}}(pass?cursor=for the next page). - Errors are
{"error": {"code", "message", "details"}}with a matching HTTP status. Common codes:unauthorized,forbidden(missing scope),validation_error,content_quota_exceeded,insufficient_credits,rate_limited,agent_post_cap_reached,agent_credit_cap_reached,agents_paused,credit_limit_exceeded,review_required(a review-first connection tried to launch a campaign),draft_time_passed. - Idempotency: creating content, launching and scheduling require an
Idempotency-Keyheader (any unique string, e.g. a UUID). Retrying with the same key and body returns the original response instead of doing the work twice. - Rate limit: 60 requests per minute per workspace (
429 rate_limitedwithdetails.retryAfter). - Billing: the API uses the same content saves and credits as the app.
The machine-readable schema is at /api/v1/public/openapi.json.
Content
Launch content
Generates (or takes from your queue) one ready-to-post item and renders it. Consumes one content save and one daily launch.
curl -X POST https://viralshaker.com/api/v1/public/launch \
-H "Authorization: Bearer $VIRALSHAKER_API_KEY" -H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" -d '{"format": "slideshow"}'
format is optional: slideshow, wall-of-text, green-screen, video-hook or notes-green-screen. The response includes contentId; the item renders in the background (poll GET /content/{id} until status is ready).
Ideas first
POST /mixer/suggestions with {"count": 7} returns post ideas (format, hook, caption, why it should work) without rendering anything. Render the ones you want with POST /launch/{suggestionId} (one content save each, Idempotency-Key), skip the rest with POST /launch/{suggestionId}/skip so the Mixer learns. POST /mixer/draft with {"format", "trendId?"} returns a ready-to-edit build spec for one format, optionally following an Inspiration trend.
Create from a spec
POST /content with {"format", "spec", "title?"} renders an explicit build spec for a template format (slideshow, wall-of-text, green-screen, video-hook, notes-green-screen). Requires Idempotency-Key. PUT /content/{id}/spec replaces a spec and re-renders; POST /content/{id}/rerender and /duplicate do what they say.
AI formats and AI Studio
GET /formats/ailists the AI formats with lengths and requirements.POST /studio/{format}/scriptwith{"durationSec", "idea?", "characterId?"}writes the script and beats (free).POST /studio/{format}/estimatewith{"spec"}returns the credit price.POST /studio/{format}/generatewith{"spec"}(andX-Max-Credits) starts the job; pollGET /studio/jobs/{jobId}.
AI Studio: POST /ai-studio/images (modelKey, prompt, count, aspectRatio) and POST /ai-studio/animate; results in GET /ai-studio/gallery; save one to the Media Bank with POST /ai-studio/assets/{id}/save. Models and prices: GET /models.
Media from a link
POST /media/from-url with {"url", "kind?": "image"|"video", "categories?", "temporary?"} imports a file (up to 500 MB) from a public https link (30 an hour). Poll GET /media/{id} until status is ready or failed (with a reason).
Upload your own video
POST /media/upload-urlwith{"filename", "contentType", "sizeBytes", "kind": "video"}→{uploadId, url, partSize, parts}. Videos can be up to 4 GB.PUTthe bytes tourl. A file over 64 MB comes back withparts> 1: send it asPUT {url}?part=1…?part={parts}, eachpartSizebytes (the last one the rest), in any order, and send a failed part again. Files up to 500 MB may also go in onePUT.POST /mediawith{"uploadId", "categories": ["demo-video"]}→ the asset (wait untilstatusisready). Add"temporary": truefor a file you only need for a day, such as a podcast episode to cut clips from: it is deleted 24 hours after upload (expiresAt), and whatever you made from it stays.POST /content/customwith{"assetId", "title?", "postCaption?"}(requiresIdempotency-Key).
Clips from a long video
POST /clips with {"assetId", "count": 5, "maxSeconds": 45, "captions": true} cuts a podcast, webinar or talk you own (a Media Bank video, 1 minute to 1 hour) into up to 8 vertical clips. We transcribe it, pick the strongest self-contained moments, crop to 9:16 and burn word-by-word captions. Each clip becomes a ready content item (origin: "clip") with a post caption, and uses one content save; transcription and picking are free. Poll GET /clips/{jobId} until status is succeeded; contentIds lists the clips. GET /clips shows recent jobs.
Read and edit
GET /content?status=&format=&limit=&cursor=andGET /content/{id}.GET /content/{id}/editablereturns the text boxes;PATCH /content/{id}with{"revision", "textBoxes": [{"id", "text"}]}re-renders (free, requiresIdempotency-Key).POST /content/{id}/regeneraterewrites the text with AI (free).GET /content/{id}/captionsandPOST /content/{id}/captionsfix burned-in captions on AI videos;POST /captions/rewritewrites a platform caption.POST /content/preview-linkwith{"ids"}returns a 7-day link where people can watch content and keep or discard it.DELETE /content/{id}.
Publishing
Accounts
GET /connections lists connected social accounts. Before scheduling, read GET /connections/{id}/rules: what the account accepts, the options it understands with allowed values (TikTok's privacy_level, YouTube's privacy, …), platform rules, and how many posts you have left today and this month. Options a platform doesn't know come back as warnings and are ignored.
GET /connect/{platform}/start returns a link for the account owner to connect an account in their browser.
Schedule
curl -X POST https://viralshaker.com/api/v1/public/content/$CONTENT_ID/schedule \
-H "Authorization: Bearer $VIRALSHAKER_API_KEY" -H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"targets": [{"connectionId": "…", "scheduledAt": "2026-11-02T17:30:00Z", "caption": "Hello #demo",
"options": {"privacy_level": "PUBLIC_TO_EVERYONE"}}]}'
Omit scheduledAt to post now; add "mode": "draft" to save drafts for review. Each target is validated against the platform's limits (422 platform_validation_failed lists the issues per account). AI-generated content is labelled automatically where the platform supports it.
The response has posts, reviewRequired (true when the posts became drafts) and a previewUrl: a 7-day page showing the posts as they'll go out, where signed-in team members can approve drafts. People approve drafts in ViralShaker; the API can't.
Post to several accounts
POST /posts writes one post for many accounts: text only, images or videos from the Media Bank (mediaAssetIds), or a content item (contentId). text is shared; a target's caption overrides it.
curl -X POST https://viralshaker.com/api/v1/public/posts \
-H "Authorization: Bearer $VIRALSHAKER_API_KEY" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
-d '{"text": "We just shipped offline mode.", "targets": [{"connectionId": "…"}, {"connectionId": "…", "options": {"first_comment": "Try it: acme.app"}}]}'
Discord (discord_username, discord_thread_id), Telegram (telegram_pin, telegram_disable_notification) and Mastodon (mastodon_visibility, mastodon_spoiler_text) have their own options; GET /connections/{id}/rules lists them all.
Text-only posts work on LinkedIn, Facebook, X, Threads, Bluesky, Google Business Profile, Discord, Telegram, Slack and Mastodon; TikTok, Instagram, YouTube and Pinterest need media. Long text on X, Threads and Bluesky becomes a thread. POST /posts/validate checks without creating anything. All posts from one call share a groupId.
Facebook Pages, LinkedIn company Pages, Pinterest boards and Google Business locations: GET /connections/{id}/targets lists them with the option name to pass (facebook_page_id, target_linkedin_page_id, pinterest_board_id, gbp_location_id); PUT /connections/{id}/default-target with {"targetId"} sets the default.
Queue, repeats and tags
GET /connections/{id}/slotsreturns an account's posting times (times, in the workspace timezone; 09:00, 13:00 and 18:00 until set) and thenextfree one;PUTwith{"times": ["08:30", "17:00"]}changes them. A target with"queue": trueand noscheduledAttakes the next free time."repeatEveryDays": 7(1–365) makes a post come back: when it publishes, a copy is scheduled that many days later.PATCH /posts/{id}with"repeatEveryDays": nullstops it."tags": ["launch"]labels posts; filter withGET /posts?tag=launch."addSignature": trueappends the workspace signature (postSignature, set in Settings orPATCH /workspaces/{id}).GET/POST /post-presetsandDELETE /post-presets/{id}save a named set of accounts, options and tags to reuse.
When the workspace has requireApproval on, posts by editors become drafts that an owner or admin approves. GET/POST /posts/{id}/comments with {"body"} holds the team's review notes.
If a platform didn't answer after we sent a post, we can't know whether it went out, so the post fails with outcome_unknown instead of being retried (no duplicates). Check the account, then retry it yourself. Network errors before anything was sent are retried automatically.
Posts
GET /posts?status=&contentId=&campaignId=&from=&to=andGET /posts/{id}.PATCH /posts/{id}changes the time, caption, title or options of a draft or scheduled post;POST /posts/{id}/retryretries a failed one.POST /posts/cancelwith{"ids": [...]}cancels scheduled posts or rejects drafts (all or nothing).POST /posts/preview-linkwith{"ids"}makes a new preview link.POST /posts/deletehides posts from lists and analytics (it doesn't delete them on the platform).
Campaigns
POST /campaigns with {"config": {name, formatWeights, connectionIds, startDate, days, postsPerAccountPerDay, timezone}} creates a draft; then POST /campaigns/{id}/preflight, /generate, /launch (requires Idempotency-Key), and /pause, /resume, /cancel. Edit slots with POST /campaigns/{id}/slots/{slotId}/reroll, PATCH (move) and DELETE; results in GET /campaigns/{id}/report. Keys set to review first can't launch or resume campaigns: people do that in ViralShaker.
Analytics
GET /analytics/accounts?days=30 returns each account's followers, the change over the period and a daily series (updated nightly; Upload-Post accounts report what the platform shares).
GET /analytics/summary?days=30 (KPIs with deltas), /timeseries, /breakdown?by=format, /top-posts and /home. POST /analytics/generate-similar with {"postId"} queues an idea like a post that did well.
Agents and MCP
ViralShaker speaks the Model Context Protocol at https://viralshaker.com/mcp (Streamable HTTP). Your agent gets a tool for everything you can do in the app (about 170), and each tool's description says what it costs and whether it publishes.
Connect
The Agents page in the app walks you through each client below, with the URL and config ready to copy. Every client signs in with OAuth: you approve the connection on a ViralShaker page, no key needed.
One connection covers every workspace you own or administer on a paid plan, including ones you add later. It starts in the workspace you pick when you approve it; ask the agent to switch (list_workspaces, switch_workspace).
Let your agent connect itself
Coding agents that can run commands (Claude Code, Codex, Cursor, Gemini CLI, VS Code, OpenClaw) can add ViralShaker on their own. Paste this into the agent:
Connect yourself to ViralShaker (my short-form video and scheduling tool) as a remote MCP server: https://viralshaker.com/mcp (Streamable HTTP, OAuth sign-in, no API key). Add it for my user, not just this project, with the command for the app you're running in:
- Claude Code: claude mcp add --transport http --scope user viralshaker https://viralshaker.com/mcp
- Codex: codex mcp add viralshaker --url https://viralshaker.com/mcp, then codex mcp login viralshaker
- Gemini CLI: gemini mcp add --transport http --scope user viralshaker https://viralshaker.com/mcp
- Cursor: add "viralshaker": {"url": "https://viralshaker.com/mcp"} under "mcpServers" in ~/.cursor/mcp.json
- VS Code: code --add-mcp '{"name":"viralshaker","type":"http","url":"https://viralshaker.com/mcp"}'
- Anything else: add a remote HTTP MCP server named viralshaker with that URL to your MCP settings.
Then tell me exactly how to finish signing in: a ViralShaker page opens in my browser where I approve the connection (you may need a restart or /mcp first). Once it works, call list_workspaces and tell me which of my workspaces you can use.
Chat apps (Claude, ChatGPT) can't add connectors themselves; add them by hand as below.
By hand
Claude (claude.ai and the desktop app): Settings → Connectors → Add custom connector, URL https://viralshaker.com/mcp. Claude Desktop's config file only runs local servers, so use the Connectors screen there too.
ChatGPT (web only): open Plugins, click + and choose Add custom MCP server. Enter the URL https://viralshaker.com/mcp under Connection, choose OAuth for authentication, tick the risk warning and click Create as a plugin. In a new chat, type @ and pick ViralShaker. Custom MCP servers need a Business, Enterprise or Edu plan (Pro gets read-only tools), and on a workspace an admin may have to allow them.
Claude Code:
claude mcp add --transport http --scope user viralshaker https://viralshaker.com/mcp
Then run /mcp in Claude Code and sign in.
Codex:
codex mcp add viralshaker --url https://viralshaker.com/mcp
codex mcp login viralshaker
Cursor (~/.cursor/mcp.json; Cursor opens the sign-in page on first use):
{ "mcpServers": { "viralshaker": { "url": "https://viralshaker.com/mcp" } } }
Gemini CLI: gemini mcp add --transport http --scope user viralshaker https://viralshaker.com/mcp, then /mcp auth viralshaker.
Clients without OAuth, servers and scripts: create a key on the Agents page and send it as a header. A key belongs to one workspace.
claude mcp add --transport http viralshaker https://viralshaker.com/mcp --header "Authorization: Bearer $VIRALSHAKER_API_KEY"
CLI and skill for agents that run shell commands (OpenClaw, Codex, Claude Code): npx viralshaker auth login, and the viralshaker skill teaches the agent the rules.
Too many tools for your client? Narrow them: https://viralshaker.com/mcp?toolsets=core,studio. Toolsets: core, studio, influencers, campaigns, analytics, inspiration, account, team (team is off unless you ask for it, or toolsets=all).
Review in the chat
Ask for a week of posts and the agent shows ideas first (list_suggestions), renders only the ones you pick, then opens a review panel in Claude or ChatGPT (show_review): the videos play in the chat, you untick what you don't want, change times or captions, and click Schedule. Your click is the approval, even for a connection set to review first. Where panels aren't available, the agent gives you a preview link instead.
Stay in control
- Review first is on by default: posts wait as drafts until you approve them.
- Daily limits per connection: 10 posts and 300 credits unless you change them on the Agents page.
- Pause all agents on the Agents page stops every connection from creating, scheduling or spending (
403 agents_paused); they can still read. An agent can pause (update_workspacewithpause_all_agents); only a person can resume. - Tools that spend credits take
max_credits; anything pricier is refused before it starts. - AI-generated videos are always labelled on every platform.
Autopilot recipes
Start these in review-first mode, check a few days of drafts, then decide.
OpenClaw (cron automation):
openclaw automations create --cron "0 8 * * 1-5" \
--prompt "Use ViralShaker: list 3 post ideas, render the best 2, wait until ready, schedule each to my TikTok for 18:00 today as drafts, and send me the preview link."
Claude scheduled tasks (with the ViralShaker connector): "Every Monday at 9:00, plan this week: show me 7 ideas, render the ones that fit our angles, and open the review panel with one post a day at 18:00."
n8n: Schedule trigger → HTTP Request POST /api/v1/public/mixer/suggestions → loop over ideas → POST /launch/{id} → wait → POST /content/{id}/schedule with "mode": "draft".
Webhooks and links
Webhooks
ViralShaker POSTs an event to your URL when something happens:
| Event | When |
|---|---|
post.published |
A post went live (the permalink is in data.permalink) |
post.failed |
A post couldn't be published (data.error) |
content.ready |
A video or image finished generating (data.files) |
content.failed |
Generation failed |
Add one in Settings → API, or:
curl -X POST https://viralshaker.com/api/v1/public/integrations/webhooks \
-H "Authorization: Bearer $VIRALSHAKER_API_KEY" -H "Content-Type: application/json" \
-d '{"url": "https://example.com/viralshaker", "events": ["post.published", "post.failed"], "connectionIds": []}'
The response holds the signing secret (whsec_…), shown once. connectionIds limits post events to those accounts; empty means all. Creating and changing webhooks needs the webhooks:write scope, which keys and connected apps only get when you tick it. A workspace can have 10.
Each request body looks like this, with the same data shape as the REST API:
{"id": "6f1c…", "type": "post.published", "createdAt": "2026-11-02T17:30:04Z", "workspaceId": "…", "data": {"id": "…", "status": "published", "permalink": "https://…"}}
Headers: X-ViralShaker-Event, X-ViralShaker-Delivery (the event id, the same on every retry, so you can skip duplicates) and X-ViralShaker-Signature: t=1793640604,v1=5f2b…. Check it before trusting the body:
import hashlib, hmac, time
def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
if abs(time.time() - int(parts["t"])) > tolerance:
return False
want = hmac.new(secret.encode(), f"{parts['t']}.".encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(want, parts["v1"])
Answer with any 2xx within 10 seconds. Anything else is retried after 1, 5 and 30 minutes, 2 and 12 hours; redirects aren't followed. After 20 failed deliveries in a row the webhook is switched off and you get a notification. The URL must be public: private and local addresses are refused.
GET /integrations/webhooks,PATCHandDELETE /integrations/webhooks/{id}("enabled": trueswitches it back on).POST /integrations/webhooks/{id}/testsends apingnow;/rotate-secretreplaces the secret.GET /integrations/webhooks/{id}/deliverieslists the last 50;POST …/deliveries/{deliveryId}/redeliversends one again.
Zapier, Make and n8n
Use the platform's own blocks: no ViralShaker app needed.
- Trigger: a "Catch Hook" (Zapier), "Custom webhook" (Make) or "Webhook" node (n8n). Copy its URL into a ViralShaker webhook.
- Actions: an HTTP request to the public API with
Authorization: Bearer <key>. For example, n8n's HTTP Request node withPOST https://viralshaker.com/api/v1/public/posts, a JSON body like the one in Publishing, and a headerIdempotency-Key: {{$execution.id}}so a re-run doesn't post twice.
A common flow: a new row in a spreadsheet → POST /posts with "mode": "draft" → someone approves it in ViralShaker → post.published → a message in Slack with the permalink.
Short links
With the link shortener set up, "shortenLinks": true on POST /posts or a schedule call (or Shorten links in Settings → Workspace for every post) turns each link in the caption, first comment and link option into its own short link. GET /posts/{id}/links returns [{url, shortUrl, clicks}]; clicks refresh hourly for 30 days after publishing. Links are left as they are when shortening fails.
X posts relayed through Upload-Post lose their links unless its link add-on is on; validation warns about it, so put the link in first_comment instead.