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"
  }
}

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.