ViralHunt

ViralHunt

ViralHunt (https://viralhunt.io) is a trending-content radar + cross-network scheduler. This skill lets you (an agent) run the full loop for the user: find what's going viral → curate it → schedule/publish it to their connected social accounts.

1. Get an API token (once)

Every call needs a personal token. The user creates one at https://viralhunt.io → Account → API Access (owner/admin), then gives it to you. It looks like vhk_.... If the user doesn't have one yet, send them there — a free 7-day trial gives them a working key.

Send it on every request:

Authorization: Bearer vhk_the_users_token

Base URL: https://viralhunt.io/tool/api/v1/ Rate limit: 100 requests/hour per token (headers X-RateLimit-Remaining / -Reset; a 429 means wait until the reset). All responses are JSON: {"success":true,"data":{…}} or {"success":false,"error":{"code","message"}}.

2. Find trending content

GET trending.php?source=&sort=&time_range=

• source: tiktok | instagram | x | facebook | pinterest | rss
• sort: viral (default), plus per-network options like most_liked, most_viewed, most_commented, newest
• time_range: 24h | 7d | 30d | 3m | all
• optional: keyword=..., min_engagement=N, page=N, per_page=N (max 100)

curl -H "Authorization: Bearer $VH" \
  "https://viralhunt.io/tool/api/v1/trending.php?source=tiktok&sort=viral&time_range=7d&per_page=10"

Returns ranked posts with engagement metrics, author, URL and thumbnail. Use this to tell the user what's gaining velocity, or to pick something to curate and repost.

3. See where you can publish

GET schedule.php?action=targets

Returns the user's projects (brands/workspaces) and the connected accounts you can post to in each:

{ "project": {"id":1,"name":"My Brand","timezone":"America/Mexico_City"},
  "projects": [ {"id":1,"name":"My Brand","networks":["instagram","facebook"],"account_count":4} ],
  "accounts": [ {"account_id":12,"network":"instagram","name":"@mybrand"} ] }

If a project has 0 accounts, the user is on a plan without connected accounts — publishing won't work until they connect accounts in the app (Agency plans).

4. Publish now or schedule

POST schedule.php?action=create with a JSON body:

{
  "project": "My Brand",              // or "project_id": 1 — REQUIRED if the org has >1 project
  "body": "Your caption text",
  "media": ["https://.../image_or_video.mp4"],   // public URLs; optional if body is set
  "target_account_ids": [12, 15],     // omit = ALL accounts in the project
  "networks": ["instagram","facebook"],// alternative to target_account_ids
  "scheduled_at": "2026-08-01T15:30:00Z", // ISO-8601 UTC; omit = publish immediately
  "first_comment": "Link in comments 👇"  // optional; posted as the first comment
}

curl -X POST -H "Authorization: Bearer $VH" -H "Content-Type: application/json" \
  -d '{"project":"My Brand","body":"Hello world","networks":["instagram"]}' \
  "https://viralhunt.io/tool/api/v1/schedule.php?action=create"

Returns { id, status, scheduled_at, targets, results, warnings }. status is processing (publishing now), scheduled (queued), partial (some targets failed — see warnings), or failed. It fans out one post per target account.

Rules to follow so you don't create bad posts:

• If the org has more than one project, you must pass project or project_id — the API refuses to guess (so a post never lands on the wrong brand).
• Only pass scheduled_at in the future, in UTC.
• Verify the content before publishing: don't repost fake news, copyrighted media, or spam — that gets the user's accounts banned. When unsure, show the user and ask.

5. Upload media (optional)

If you have a local file instead of a URL:

POST schedule.php?action=upload — multipart form field file (jpg/png/gif/webp/mp4/mov, ≤50MB). Returns { "url": "https://..." }. Pass that URL in media on create.

6. Edit or cancel a scheduled post

Posts can be edited ONLY while their status is scheduled (not yet publishing), and PostProxy won't allow an edit less than ~5 minutes before publish time.

• Cancel: POST schedule.php?action=cancel — {"id": 123}. Cancels the not-yet-published targets. If everything already published you get 409 already_published.
• Update: POST schedule.php?action=update — {"id": 123, "body": "...", "media": ["..."], "networks": ["facebook"], "scheduled_at": "2026-08-01T15:30:00Z"}. Only the fields you send change. The project cannot be changed.

Agent rules:

• Before editing, GET schedule.php?action=get&id=123 and confirm status is scheduled.
• On 409 (already publishing/published or too close to publish time), re-fetch and tell the user — never retry an update blindly.
• After any edit, GET again and confirm the change landed before reporting done.

7. Check status

GET schedule.php?action=get&id= → the post's current status and per-network results. Call POST schedule.php?action=sync first to refresh from the networks.

Editorial board (optional)

You can also organize work on the user's kanban board instead of publishing directly: GET columns.php, GET my-cards.php (cards assigned to you), POST cards.php (create a card), GET/POST comments.php. See the full docs at https://viralhunt.io/api.

Error handling

Always surface the error.message to the user verbatim — it explains exactly what to fix.