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 by URL. Consumes one catalog slot. Draws down: Catalog slot — standing cap, does not reset. Also exposed as the MCP tool analyze_tiktok_video.
• GET /v1/analyses/{job_id} — Poll an analysis job until it reaches a terminal status.

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. Does not return videos, and carries no per-video AI analysis — that requires analyze_tiktok_video. Also exposed as the MCP tool browse_niche_catalog.
• GET /v1/niches/{id}/videos — Top videos for one niche, ranked by multiplier.

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 — poll GET /v1/trends/search/{job_id} until status is "completed", then read the results from that response. Draws down: Trend search — monthly allowance. Also exposed as the MCP tool search_viral_trends.
• GET /v1/trends/search/{job_id} — Poll a trend search job until it reaches a terminal status.

scripts

• POST /v1/scripts — Generate a script grounded in the workspace top performers. Always returns a job handle (202), never the script itself — generation can take up to a minute. Poll GET /v1/scripts/jobs/{job_id} until status is "completed", then fetch the script from result_path. Draws down: Script — monthly allowance. Also exposed as the MCP tool generate_script.
• GET /v1/scripts/jobs/{job_id} — Poll a script generation job until it reaches a terminal status.
• 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. 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 in this workspace by username, view count, or date range. Also exposed as the MCP tool search_videos.
• GET /v1/videos/{id}/analysis — Full AI analysis for one video: hook, timing, scenes, transcript. Also exposed as the MCP tool get_video_analysis.
• GET /v1/videos/{id}/similar — Find videos similar to a given video using vector search. 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.