REST reference

The response envelope

Every response is one of three shapes. A single object: {"data": {...}}. A list: {"data": [...], "meta": {"page", "limit", "total", "total_pages", "has_more"}}. An error: {"error": {"code", "message", "details"?}}. message is always a string, never a string-or-array union, so a client can render it directly and branch on code instead.

Pagination

List endpoints take page (default 1) and limit (default 50, max 200) query parameters. Out-of-range values are clamped, never rejected — a request for limit=5000 gets 200 rows back with meta.limit reflecting what actually happened, not a 400.

The async job pattern

POST /v1/analyses, POST /v1/niches, POST /v1/trends/search and POST /v1/scripts can all return 202 with a job_id/poll_url/retry_after_seconds instead of a result — analysis and generation don't finish inside one request. Poll the matching GET .../jobs/{id} (or job-shaped) endpoint until status reaches a terminal value (completed or failed); never treat a non-terminal status as done.

Endpoints

analyses

• POST /v1/analyses — Analyze a TikTok video or photo slideshow by URL (/video/ or /photo/ links). Consumes one catalog slot. TikTok URLs only: YouTube Shorts are analyzed in the fypnow.com web app, not here. Draws down: Catalog slot — standing cap, does not reset. Also exposed as the MCP tool analyze_tiktok_video.
• GET /v1/analyses/{job_id} — Resolves the job handle returned by analyze_tiktok_video into the finished analysis. Status is processing, completed or failed, and the response carries a retry_after_seconds hint for how long to wait between attempts while it is still processing. Also exposed as the MCP tool get_analysis_result.

niches

• POST /v1/niches — Create a Viral Content Agent that watches a niche by keyword. Draws down: Custom niche (Viral Content Agent) slot — standing cap. Also exposed as the MCP tool create_niche.
• GET /v1/niches — Browse available niches with their stats and metadata. Returns niches only, not videos, and carries no per-video AI analysis; that lives behind analyze_tiktok_video. Also exposed as the MCP tool browse_niche_catalog.
• GET /v1/niches/{id}/videos — Top videos in one niche, ranked by how far they outperformed the niche's median (multiplier). Takes a niche id from browse_niche_catalog. Returns catalogue stats — views, likes, author, multiplier, platform — not per-video AI analysis. Niches mix TikToks and YouTube Shorts; platform is 'tiktok' or 'youtube'. A hook and scene teardown of a TikTok comes from analyze_tiktok_video, which takes its URL; that tool does not accept YouTube Shorts. Each row carries post_format; the format input ('video' or 'slideshow') narrows the list to one. Also exposed as the MCP tool get_niche_videos.

trends

• POST /v1/trends/search — Search for breakout videos by hashtag. A cached hashtag returns full results right away. An uncached one returns a job handle (202) with no results yet; that handle is resolved by get_trend_search_result, which reports status complete or error and carries the results. Draws down: Trend search — monthly allowance. Also exposed as the MCP tool search_viral_trends.
• GET /v1/trends/search/{job_id} — Resolves the job handle returned by search_viral_trends into the finished results. Status is pending, complete or error, and the response carries a retry_after_seconds hint for how long to wait between attempts. A search already in flight is resolved here; starting another for the same hashtag spends a second viral search from the monthly allowance. Also exposed as the MCP tool get_trend_search_result.

scripts

• POST /v1/scripts — Generate a script grounded in the workspace top performers. Returns a job handle (202) rather than the script itself, because generation takes up to a minute. The handle is resolved by get_script_result, which reports status completed or failed and carries the script. Draws down: Script — monthly allowance. Also exposed as the MCP tool generate_script.
• GET /v1/scripts/jobs/{job_id} — Resolves the job handle returned by generate_script into the finished script. Status is processing, completed or failed, and the response carries a retry_after_seconds hint for how long to wait between attempts while it is still processing. Also exposed as the MCP tool get_script_result.
• GET /v1/scripts — List generated scripts.
• GET /v1/scripts/{id} — Fetch one generated script.

library

• POST /v1/library — Save a video to the workspace library. Works for TikToks and YouTube Shorts; pass platform ('tiktok' or 'youtube') from get_niche_videos, or omit it and a YouTube-shaped id is saved as a Short. Also exposed as the MCP tool save_video.
• DELETE /v1/library/{video_id} — Remove a video from the library.
• GET /v1/library — List saved videos.

videos

• GET /v1/videos — Search analyzed videos and slideshows in this workspace by username, view count, date range, or format ('video' or 'slideshow'). Each row carries platform ('tiktok' or 'youtube') and post_format ('photo' carousel, 'slideshow' template, 'video', or null for a video). Also exposed as the MCP tool search_videos.
• GET /v1/videos/{id}/analysis — Full AI analysis for one video or slideshow. A video returns hook, timing, scenes and transcript; a slideshow (schema_version carousel_v1) returns cover, slide-by-slide breakdown, narrative, aesthetic, audio, swipe and save drivers, and scores. Also exposed as the MCP tool get_video_analysis.
• GET /v1/videos/{id}/similar — Find videos or slideshows similar to a given one using vector search. Each row carries post_format. Also exposed as the MCP tool find_similar_videos.

breakouts

• GET /v1/breakouts — List videos currently breaking out among tracked creators. Also exposed as the MCP tool list_breakouts.

creators

• GET /v1/creators — List tracked creators in this workspace, with their ids. Also exposed as the MCP tool list_creators.
• GET /v1/creators/{id}/report — Profile, follower history and winning patterns for one creator. Also exposed as the MCP tool get_creator_report.

growth

• GET /v1/growth/scorecard — Grade the workspace own account against its niche benchmarks. Also exposed as the MCP tool get_growth_scorecard.

usage

• GET /v1/usage — Current plan allowances and consumption. Free and unmetered. Also exposed as the MCP tool get_account_usage.

Error codes

Generated from the same code that raises these errors, so this table cannot list a code the API doesn't actually return.

• 403 api_access_required — This workspace does not have an active plan.
• 422 catalog_full — The workspace has reached its (standing) video catalog cap.
• 403 connection_revoked — This OAuth connection has been revoked. Reconnect from Settings.
• 403 forbidden — The credential's owning user cannot perform this action.
• 500 internal_error — Something went wrong on our end.
• 401 invalid_api_key — The credential is not a recognised API key or a valid Supabase OAuth token.
• 400 invalid_url — The provided URL is not a TikTok video link.
• 422 library_full — The workspace library is at its 5,000-video cap.
• 401 missing_api_key — No credential was provided in the Authorization header.
• 422 niche_limit_reached — The workspace has reached its custom niche allowance.
• 404 not_found — No such resource in this workspace.
• 501 not_implemented — This endpoint is not available yet.
• 429 rate_limit_exceeded — Too many requests in the trailing 60-second window.
• 401 revoked_api_key — That API key has been revoked.
• 422 script_limit_reached — The workspace has reached its monthly script allowance.
• 422 search_limit_reached — The workspace has reached its monthly trend-search allowance.
• 422 search_miss_limit_reached — The workspace has reached its daily uncached-search allowance.
• 502 upstream_error — A downstream service failed or returned something unexpected.
• 400 validation_error — The request body or parameters failed validation.
• 403 write_scope_required — This credential is read-only.