ViralHunt API v1

Authentication

All endpoints (except this docs page) require an API key. Keys are aMember SoftSale license keys assigned to your user account.

Sending Your Key

Recommended: Use the Authorization header:

Authorization: Bearer YOUR_API_KEY

Alternative: Query parameter (less secure, useful for quick tests):

GET /api/v1/trending.php?source=rss&api_key=YOUR_API_KEY

Getting a Key

Contact your admin to generate a SoftSale license key in the aMember admin panel. The key is tied to your user account and inherits your organization membership.

Rate Limits

API requests are limited to 100 requests per hour per API key (fixed window).

Every response includes rate limit headers:

When exceeded, the API returns 429 Too Many Requests.

Error Codes

Errors return a JSON envelope:

{
  "success": false,
  "error": {
    "code": "auth_required",
    "message": "API key required."
  }
}

Trending Posts

Query trending and viral posts across platforms.

Sort Options by Source

Example

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://viralhunt.io/tool/api/v1/trending.php?source=rss&sort=trending&time_range=7d&per_page=5"

{
  "success": true,
  "data": {
    "posts": [
      {
        "id": 123,
        "title": "Why AI is changing everything",
        "url": "https://example.com/article",
        "image_url": "https://example.com/img.jpg",
        "facebook_shares": 1200,
        "reddit_score": 500,
        "pinterest_shares": 300,
        "total_engagement": 2000,
        "trend_score": 85.0,
        "growth_rate": 25.5,
        "feed_name": "TechCrunch",
        "category_id": 3,
        "category_name": "Technology"
      }
    ]
  },
  "meta": {
    "page": 1,
    "per_page": 5,
    "total": 142,
    "total_pages": 29,
    "has_more": true
  }
}

Create Card

Create a new card on the Editorial Board.

Auto-extraction: If title is omitted but post_url is provided, the API will fetch the URL and extract the title, description, image, and platform automatically from Open Graph / meta tags. If extraction fails, a 422 error is returned asking for a manual title.

Example: With Title

curl -X POST -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Review viral TikTok video","priority":"high","post_url":"https://tiktok.com/...","platform":"tiktok"}' \
  https://viralhunt.io/tool/api/v1/cards.php

{
  "success": true,
  "data": {
    "card_id": 42,
    "title": "Review viral TikTok video",
    "status": "pending",
    "board_column_id": 1,
    "position": 5
  }
}

Example: URL Only (Auto-Extract)

curl -X POST -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"post_url":"https://techcrunch.com/2026/02/19/some-article/","assigned_to_user_id":7,"priority":"high"}' \
  https://viralhunt.io/tool/api/v1/cards.php

{
  "success": true,
  "data": {
    "card_id": 43,
    "title": "Some Article Title Extracted From Page",
    "status": "pending",
    "board_column_id": 1,
    "position": 6,
    "auto_extracted": true,
    "description": "Description extracted from og:description...",
    "image_url": "https://techcrunch.com/img/hero.jpg",
    "platform": "web"
  }
}

Schedule / Publish to Social Networks

Publish or schedule a post — text plus media (e.g. a video) — to a project's connected social accounts. Fans out to one post per target, like the in-app composer. Requires the org to have connected accounts (Agency plans).

GET /api/v1/schedule.php?action=targets

Discover where you can post. Optional: &project=NAME or &project_id=ID (defaults to the org's first project). Returns projects[] — EVERY project in the org, each with {id, name, timezone, networks[], account_count} so you can pick which project + networks — plus project (the resolved one) and accounts[] (its postable accounts: account_id, network, name).

POST /api/v1/schedule.php?action=upload

Upload one media file (multipart field file; mp4/mov/jpg/png/gif/webp, ≤50MB) → { "url", "type" }. Use that url in media. Skip if your media is already a public URL.

POST /api/v1/schedule.php

Publish now or schedule. JSON body:

{
  "project": "Viral Hunt",                 // or "project_id": N; omit = first project
  "body": "your caption",
  "media": ["https://.../video.mp4"],      // omit for text-only
  "target_account_ids": [12, 15],          // omit = ALL connected accounts in the project
  "scheduled_at": "2026-08-01T15:30:00Z",  // ISO-8601 UTC; omit = publish now
  "first_comment": "optional first comment"
}

Returns { id, status, targets, results, warnings }. Check status later with GET /api/v1/schedule.php?action=get&id=ID.

Example: publish a video now

curl -X POST -H "Authorization: Bearer YOUR_KEY" \
  -F "file=@video.mp4" \
  "https://viralhunt.io/tool/api/v1/schedule.php?action=upload"
# then, with the returned url:
curl -X POST -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"project":"Viral Hunt","body":"New drop","media":["URL_FROM_UPLOAD"]}' \
  https://viralhunt.io/tool/api/v1/schedule.php

Team Members

List members of your organization.

curl -H "Authorization: Bearer YOUR_KEY" \
  https://viralhunt.io/tool/api/v1/members.php

{
  "success": true,
  "data": {
    "members": [
      {"user_id": 1, "user_name": "Jane Doe", "user_email": "jane@example.com", "role": "owner"},
      {"user_id": 5, "user_name": "John", "user_email": "john@example.com", "role": "member"}
    ]
  }
}

Organization Info

Get details about your organization.

curl -H "Authorization: Bearer YOUR_KEY" \
  https://viralhunt.io/tool/api/v1/organization.php

{
  "success": true,
  "data": {
    "id": 1,
    "name": "My Team",
    "team_size": 5,
    "timezone": "America/New_York",
    "niche_tags": ["tech", "AI", "startups"],
    "created_at": "2024-06-15 10:00:00"
  }
}

Board Columns

List Editorial Board columns. Auto-creates defaults if none exist.

curl -H "Authorization: Bearer YOUR_KEY" \
  https://viralhunt.io/tool/api/v1/columns.php

{
  "success": true,
  "data": {
    "columns": [
      {"id": 1, "name": "To Review", "color": "#6366f1", "position": 0, "is_default": true, "is_done": false},
      {"id": 2, "name": "In Progress", "color": "#f59e0b", "position": 1, "is_default": false, "is_done": false},
      {"id": 5, "name": "Published", "color": "#10b981", "position": 4, "is_default": false, "is_done": true}
    ]
  }
}

Board Categories

List active board categories for tagging cards.

curl -H "Authorization: Bearer YOUR_KEY" \
  https://viralhunt.io/tool/api/v1/categories.php

{
  "success": true,
  "data": {
    "categories": [
      {"id": 1, "name": "General", "color": "#6b7280", "icon": "fa-folder"},
      {"id": 2, "name": "Urgent", "color": "#ef4444", "icon": "fa-fire"},
      {"id": 3, "name": "Ideas", "color": "#8b5cf6", "icon": "fa-lightbulb"}
    ]
  }
}

Workspace Context

Get combined workspace context in a single call: organization info, team members, board columns, and categories. Ideal for bot integrations that need full context before taking actions.

curl -H "Authorization: Bearer YOUR_KEY" \
  https://viralhunt.io/tool/api/v1/context.php

{
  "success": true,
  "data": {
    "organization": {
      "id": 1,
      "name": "My Team",
      "team_size": 5,
      "timezone": "America/New_York",
      "niche_tags": ["tech", "AI", "startups"],
      "created_at": "2024-06-15 10:00:00"
    },
    "members": [
      {"user_id": 1, "user_name": "Jane Doe", "user_email": "jane@example.com", "role": "owner"},
      {"user_id": 5, "user_name": "John", "user_email": "john@example.com", "role": "member"}
    ],
    "columns": [
      {"id": 1, "name": "To Review", "color": "#6366f1", "position": 0, "is_default": true, "is_done": false},
      {"id": 5, "name": "Published", "color": "#10b981", "position": 4, "is_default": false, "is_done": true}
    ],
    "categories": [
      {"id": 1, "name": "General", "color": "#6b7280", "icon": "fa-folder"},
      {"id": 2, "name": "Urgent", "color": "#ef4444", "icon": "fa-fire"}
    ]
  }
}

Pending Cards

Get pending and in-progress cards grouped by assigned team member. Useful for bot reminders and workload overview.

curl -H "Authorization: Bearer YOUR_KEY" \
  https://viralhunt.io/tool/api/v1/pending.php

{
  "success": true,
  "data": {
    "summary": {
      "total_pending": 8,
      "total_urgent": 2,
      "total_overdue": 1,
      "total_unassigned": 1
    },
    "members": [
      {
        "user_id": 7,
        "user_name": "Alejandra Galaz",
        "total": 3,
        "urgent": 1,
        "overdue": 1,
        "cards": [
          {
            "card_id": 42,
            "title": "Review: NASA Starliner Report",
            "priority": "high",
            "status": "pending",
            "due_date": "2026-02-18",
            "is_overdue": true,
            "column_name": "To Review",
            "post_url": "https://nasa.gov/..."
          }
        ]
      }
    ],
    "unassigned": [...]
  }
}

Try It

Test API endpoints live from your browser.