ViralShaker로 개발하기

나만의 도구와 AI 어시스턴트를 위한 REST API와 MCP 서버예요.

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": true and includes a previewUrl.
  • 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-Key header (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_limited with details.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

  1. GET /formats/ai lists the AI formats with lengths and requirements.
  2. POST /studio/{format}/script with {"durationSec", "idea?", "characterId?"} writes the script and beats (free).
  3. POST /studio/{format}/estimate with {"spec"} returns the credit price.
  4. POST /studio/{format}/generate with {"spec"} (and X-Max-Credits) starts the job; poll GET /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.

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

  1. POST /media/upload-url with {"filename", "contentType", "sizeBytes", "kind": "video"} → {uploadId, url, partSize, parts}. Videos can be up to 4 GB.
  2. PUT the bytes to url. A file over 64 MB comes back with parts > 1: send it as PUT {url}?part=1 … ?part={parts}, each partSize bytes (the last one the rest), in any order, and send a failed part again. Files up to 500 MB may also go in one PUT.
  3. POST /media with {"uploadId", "categories": ["demo-video"]} → the asset (wait until status is ready). Add "temporary": true for 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.
  4. POST /content/custom with {"assetId", "title?", "postCaption?"} (requires Idempotency-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= and GET /content/{id}.
  • GET /content/{id}/editable returns the text boxes; PATCH /content/{id} with {"revision", "textBoxes": [{"id", "text"}]} re-renders (free, requires Idempotency-Key).
  • POST /content/{id}/regenerate rewrites the text with AI (free).
  • GET /content/{id}/captions and POST /content/{id}/captions fix burned-in captions on AI videos; POST /captions/rewrite writes a platform caption.
  • POST /content/preview-link with {"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}/slots returns an account's posting times (times, in the workspace timezone; 09:00, 13:00 and 18:00 until set) and the next free one; PUT with {"times": ["08:30", "17:00"]} changes them. A target with "queue": true and no scheduledAt takes 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": null stops it.
  • "tags": ["launch"] labels posts; filter with GET /posts?tag=launch.
  • "addSignature": true appends the workspace signature (postSignature, set in Settings or PATCH /workspaces/{id}).
  • GET/POST /post-presets and DELETE /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= and GET /posts/{id}.
  • PATCH /posts/{id} changes the time, caption, title or options of a draft or scheduled post; POST /posts/{id}/retry retries a failed one.
  • POST /posts/cancel with {"ids": [...]} cancels scheduled posts or rejects drafts (all or nothing).
  • POST /posts/preview-link with {"ids"} makes a new preview link.
  • POST /posts/delete hides 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_workspace with pause_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, PATCH and DELETE /integrations/webhooks/{id} ("enabled": true switches it back on).
  • POST /integrations/webhooks/{id}/test sends a ping now; /rotate-secret replaces the secret.
  • GET /integrations/webhooks/{id}/deliveries lists the last 50; POST …/deliveries/{deliveryId}/redeliver sends 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 with POST https://viralshaker.com/api/v1/public/posts, a JSON body like the one in Publishing, and a header Idempotency-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.

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.