BUILD ON THE
VIRAL ENGINE.

GET /videos

List analyzed videos with filtering and sorting.

curl "https://api.blossai.com/api/v1/videos?platform=tiktok&min_views=100000&sort_by=engagement_rate&limit=10" \
  -H "X-API-Key: $BLOSSOM_API_KEY"

{
  "data": [
    {
      "id": 18234,
      "platform": "tiktok",
      "username": "creator_handle",
      "content_type": "video",
      "content_url": "https://www.tiktok.com/@creator_handle/video/...",
      "caption": "POV: you finally understand the algorithm",
      "duration_sec": 27,
      "views": 1283000,
      "likes": 145200,
      "comments": 3100,
      "shares": 8900,
      "saves": 12400,
      "engagement_rate": 13.2,
      "published_at": "2026-05-28T16:00:00.000Z",
      "hashtags": ["#fyp", "#tutorial"],
      "thumbnail_url": "https://...",
      "format_id": 4,
      "format_name": "Talking Head Tutorial",
      "hook_id": 9,
      "hook_name": "Direct Question",
      "final_viral_probability": 0.82
    }
  ],
  "pagination": { "total": 1543, "limit": 10, "offset": 0, "has_more": true },
  "meta": { "timestamp": "2026-06-12T10:00:00.000Z" }
}

GET /videos/:id

Full detail for one video.

Everything from the list payload plus the full analysis JSON, the format/hook classification with confidence, detected tactics with execution scores, keywords with relevance weights, and linked music.

curl "https://api.blossai.com/api/v1/videos/18234" \
  -H "X-API-Key: $BLOSSOM_API_KEY"

{
  "data": {
    "id": 18234,
    "platform": "tiktok",
    "...": "all list fields, plus:",
    "analysis_json": { "...": "full AI analysis" },
    "classification": {
      "format_id": 4, "format_name": "Talking Head Tutorial",
      "hook_id": 9, "hook_name": "Direct Question",
      "confidence": 0.94
    },
    "tactics": [
      { "id": 7, "name": "Fast cuts", "category": "editing", "viewer_effect": "retention", "execution_score": 8.5 }
    ],
    "keywords": [
      { "id": 112, "name": "productivity", "category": "topic", "relevance_weight": 0.91 }
    ],
    "music": [
      { "id": 12, "title": "Track Name", "artist": "Artist", "platform": "tiktok", "video_count": 234 }
    ]
  },
  "meta": { "timestamp": "2026-06-12T10:00:00.000Z" }
}

GET /influencers

List creators with filtering and sorting.

curl "https://api.blossai.com/api/v1/influencers?tier=micro&sort_by=avg_engagement_rate" \
  -H "X-API-Key: $BLOSSOM_API_KEY"

GET /influencers/:id

Single creator profile with performance stats and recent videos.

GET /formats

Viral format classes with usage counts and trend stats.

GET /formats/:id

Single format class detail.

GET /hooks

Hook classes — the opening techniques that stop the scroll.

GET /hooks/:id

Single hook class detail.

GET /tactics

The tactics library — granular techniques detected inside videos.

GET /tactics/:id

Single tactic detail.

GET /music

Music tracks used across the analyzed library.

GET /music/:id

Single track detail with usage stats.

GET /suggestions

AI-generated content suggestions ranked by trend strength.

GET /suggestions/:id

Single suggestion detail.

GET /categories

Content categories visible to the calling key's scope.

If your key is scoped to specific categories, only those are returned; unscoped keys see every category available to your plan.

GET /trending/posts

Recently analyzed posts ordered by recency and views.

GET /trending/formats

Format classes ranked by recent momentum.

Each row includes trend_velocity, lifecycle_stage, recent_video_count, recent_avg_views, and last_24h_count so you can separate rising formats from saturated ones.

GET /trending/hooks

Hook classes ranked by recent momentum.

GET /trending/songs

Songs ranked by a velocity-weighted trending score.

The trending_score combines 3-hour, 24-hour, and 7-day usage with acceleration (velocity) and average views — built to surface sounds before they peak.

curl "https://api.blossai.com/api/v1/trending/songs?days=7&limit=5" \
  -H "X-API-Key: $BLOSSOM_API_KEY"

{
  "data": [
    {
      "id": 412,
      "title": "Track Name",
      "artist": "Artist",
      "platform": "tiktok",
      "total_video_count": 234,
      "total_views": 18200000,
      "recent_video_count": 41,
      "count_3h": 6,
      "count_24h": 19,
      "count_7d": 41,
      "recent_avg_views": 510000,
      "velocity": 2.4,
      "trending_score": 196.32
    }
  ],
  "meta": { "days": 7, "timestamp": "2026-06-12T10:00:00.000Z" }
}

POST /analysis

Trigger analysis for a TikTok or Instagram URL.

Returns 202 Accepted immediately with an analysis_id. Poll GET /analysis/:id for progress and the final result.

• Analyses share your dashboard quota: 50/hour on Pro, 100/hour on Agency. Exceeding it returns 429 hourly_quota_exceeded.

curl -X POST "https://api.blossai.com/api/v1/analysis" \
  -H "X-API-Key: $BLOSSOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.tiktok.com/@creator/video/1234567890" }'

{
  "data": {
    "analysis_id": 4821,
    "status": "pending",
    "platform": "tiktok",
    "username": "creator",
    "thumbnail_url": "https://...",
    "caption": "...",
    "views": 1283000
  },
  "meta": { "timestamp": "2026-06-12T10:00:00.000Z" }
}

POST /analysis/upload

Analyze a video file before you post it anywhere.

Send multipart/form-data with the video in a video field. Same async flow and quotas as the URL trigger.

• Oversize files return 413 file_too_large; non-video uploads return 400 invalid_file.

curl -X POST "https://api.blossai.com/api/v1/analysis/upload" \
  -H "X-API-Key: $BLOSSOM_API_KEY" \
  -F "video=@./draft-reel.mp4" \
  -F "caption=POV: my first launch video"

GET /analysis/:id

Poll analysis status and fetch the result.

status moves through pending → processing → complete (or failed, with error set). While running, a steps object reports per-stage progress. Once complete, result contains the five analysis payloads. Recommended polling cadence: every 5 seconds — most analyses finish in 20–45s.

curl "https://api.blossai.com/api/v1/analysis/4821" \
  -H "X-API-Key: $BLOSSOM_API_KEY"

{
  "data": {
    "id": 4821,
    "status": "complete",
    "error": null,
    "result": {
      "full_analysis": { "...": "scene-by-scene breakdown" },
      "hook_analysis": { "...": "first-3-seconds analysis" },
      "virality": { "...": "platform virality scores" },
      "improvements": { "...": "ranked improvement suggestions" },
      "benchmarks": { "...": "category benchmarks" }
    }
  },
  "meta": { "timestamp": "2026-06-12T10:01:00.000Z" }
}

GET /social/accounts

List your connected social accounts.

GET /social/accounts/:id

Single connected account.

POST /social/accounts/:id/sync-profile

Refresh profile metadata (name, bio, follower count, avatar) from the platform.

POST /social/accounts/:id/sync-posts

Pull the account's latest posts into Blossom and refresh their metrics.

GET /social/posts

List posts created or synced for your account.

GET /social/posts/:id

Single post, including a metricsHistory array of snapshots.

POST /social/posts

Create a post as a draft (or with scheduling metadata).

Creating and publishing are separate steps — see POST /social/posts/:id/publish. Returns 201 Created with the full post row.

• Platform rules are validated on create: Instagram post = 1 image, video/reel = 1 video, carousel = 2–10 mixed; TikTok video = 1 video (≤4GB), carousel = 2–35 images. Stories are not supported.
• By default media_urls must point at Blossom-hosted (Supabase) storage. Arbitrary external hosts are rejected with 400 bad_request unless external media is enabled for your deployment.

curl -X POST "https://api.blossai.com/api/v1/social/posts" \
  -H "X-API-Key: $BLOSSOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 17,
    "content_type": "carousel",
    "caption": "Behind the scenes of launch week #launch #bts",
    "media_urls": ["https://...storage.../img1.jpg", "https://...storage.../img2.jpg"]
  }'

PATCH /social/posts/:id

Update a draft or scheduled post.

Same fields as create, except account_id is immutable. media_urls semantics: omitted = keep existing media, [] = clear all, non-empty = replace wholesale.

POST /social/posts/:id/media

Append media URLs without replacing existing media.

• The combined media list is re-validated against the platform rules — exceeding a limit (e.g. 10 items on an Instagram carousel) returns 400 bad_request.

POST /social/posts/:id/publish

Publish a draft or scheduled post now.

Instagram publishes synchronously — the response has status: "published" with platform_post_id and the canonical post_url. TikTok is asynchronous — the response has status: "publishing" and a publish_id; poll GET /social/posts/:id until it resolves to published or failed.

• scheduled_for is planning metadata surfaced in the dashboard — there is no autopilot. Even scheduled posts publish only when this endpoint (or the dashboard button) is called.

curl -X POST "https://api.blossai.com/api/v1/social/posts/902/publish" \
  -H "X-API-Key: $BLOSSOM_API_KEY"

GET /social/posts/:id/metrics

Historical metric snapshots (likes, views, comments, shares, saves) for a published post.

GET /social/analytics/dashboard

Top-level stats across all connected accounts.

GET /social/analytics/overview

Aggregated engagement and reach over a time window.

GET /account

The calling key's plan, rate limit, usage counters, and quotas.

curl "https://api.blossai.com/api/v1/account" \
  -H "X-API-Key: $BLOSSOM_API_KEY"

{
  "data": {
    "plan": { "slug": "pro", "name": "Pro" },
    "rate_limit": { "per_minute": 30, "window": "60s" },
    "usage": { "today": 14, "last_30_days": 287, "total": 1203 },
    "quotas": { "monthly_analyses": null }
  },
  "meta": { "timestamp": "2026-06-12T10:00:00.000Z" }
}