REST API

A TikTok API for research, not posting

TikTok’s own API tells you about accounts you own. This one tells you why someone else’s video worked — the hook, where the scenes cut, what the transcript says, how far it outran its creator’s baseline.

22 endpoints, OpenAPI 3.1, and the same surface again as an MCP server for AI agents. Included on every paid plan.

Start a free trial API reference

Analyze a video in one call

curl -X POST https://api.fypnow.com/v1/analyses \
  -H "Authorization: Bearer fyp_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@someone/video/123"}'

# 202 Accepted
{ "data": { "job_id": "...", "status": "processing",
            "poll_url": "/v1/analyses/...", "retry_after_seconds": 30 } }

Analysis runs a video model, so it returns a job handle rather than blocking. Poll the job, then read the full teardown — hook type and text, scene count and timings, transcript with timestamps, retention signals and virality factors.

22 endpoints, 18 as agent tools

Generated from the API’s own route table. Reads cost nothing beyond the request; writes draw down a plan quota.

Read (16)

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.

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.

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.

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).

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.

GET /v1/videos/{id}/similar

Find videos or slideshows similar to a given one using vector search. Each row carries post_format.

GET /v1/breakouts

List videos currently breaking out among tracked creators.

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.

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.

GET /v1/creators

List tracked creators in this workspace, with their ids.

GET /v1/creators/{id}/report

Profile, follower history and winning patterns for one creator.

GET /v1/scripts

List generated scripts.

GET /v1/scripts/{id}

Fetch one generated script.

GET /v1/library

List saved videos.

GET /v1/growth/scorecard

Grade the workspace own account against its niche benchmarks.

GET /v1/usage

Current plan allowances and consumption. Free and unmetered.

Write (6)

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.

POST /v1/niches

Create a Viral Content Agent that watches a niche by keyword.

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.

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.

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.

DELETE /v1/library/{video_id}

Remove a video from the library.

Built to be integrated against

One response shape

Every endpoint returns {"data": …} or {"error": {"code", "message"}}. `message` is always a string — never a string-or-array union that forces defensive parsing.

Machine-readable error codes

Branch on `code`, not on prose. catalog_full, write_scope_required, rate_limit_exceeded, api_access_required — each means one thing.

Honest coverage

Responses report what is missing rather than nulling it silently. If a transcript could not be extracted, the payload says so.

Generated spec

The OpenAPI document and the docs are generated from the route table the API dispatches on, so they cannot describe an endpoint that does not exist.

Async where it matters

Anything that runs a model or reaches TikTok returns a job handle with a poll URL and a realistic retry interval.

One workspace per credential

No request parameter can reach a second workspace. Entitlement is re-checked on every request, not at key creation.

Questions

Is there a TikTok analytics API?

TikTok's own API is built for posting and for Business accounts you own — it will not tell you what is working on someone else's account. FYPNow's API is a research API: it returns AI teardowns of any public TikTok video (hook, scene timing, transcript, retention signals), viral trend search by hashtag, creator breakout detection, and a browsable catalogue of niche-level top performers.

How much does the API cost?

Nothing extra. REST API and MCP access are included on every paid plan with no separate add-on fee. Reads cost nothing beyond the request; the endpoints that reach TikTok or run AI analysis draw down the same quotas the dashboard uses, so there is one bill and one set of limits.

How do I authenticate?

A bearer API key, created in Settings → API and sent as Authorization: Bearer fyp_sk_.... Keys are scoped read or read+write, shown once at creation, and stored only as a SHA-256 hash. OAuth 2.1 is also supported for MCP clients such as Claude. Every credential is bound to exactly one workspace.

Is there an OpenAPI spec?

Yes — a generated OpenAPI 3.1 document at https://api.fypnow.com/openapi.json, suitable for typed client generation. It is produced from the same route table the API dispatches on, so it cannot drift from the implementation. A rendered reference lives at /docs/api.

How does video analysis work over the API?

POST a TikTok URL to /v1/analyses and you get a job handle back immediately, because the analysis runs a video model and takes roughly a minute. Poll the job until it completes, then read the result. The same pattern covers script generation and trend search. Every async response tells you where to poll and how long to wait.

Does the API support YouTube Shorts?

Not yet. The API is TikTok-only, and /v1/analyses rejects YouTube links. The FYPNow web app does analyze YouTube Shorts — paste a Shorts link into the analyzer for the same breakdown a TikTok gets. See the YouTube Shorts analysis page.

Can I use it from an AI agent?

That is what it was built for. The same surface is exposed as an MCP server, so Claude and other MCP clients can call it as tools without you writing any HTTP code. See the MCP server page.

No API add-on, no separate bill

Every paid plan includes the REST API and the MCP server, against the same quotas you already have.

See plans Getting started