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}

Fetch the result of an analyze_tiktok_video job by its job_id. Call this after analyze_tiktok_video returns a job handle, waiting retry_after_seconds between attempts, until status is completed or failed.

GET /v1/scripts/jobs/{job_id}

Fetch the result of a generate_script job by its job_id. Call this after generate_script returns a job handle, waiting retry_after_seconds between attempts, until status is completed or failed.

GET /v1/trends/search/{job_id}

Fetch the result of a search_viral_trends job by its job_id. Call this after search_viral_trends returns a job handle, waiting retry_after_seconds between attempts, until status is complete or error. Do NOT call search_viral_trends again for the same hashtag while a job is still running -- each call spends a fresh viral search from the monthly allowance.

GET /v1/videos

Search analyzed videos in this workspace by username, view count, or date range.

GET /v1/videos/{id}/analysis

Full AI analysis for one video: hook, timing, scenes, transcript.

GET /v1/videos/{id}/similar

Find videos similar to a given video using vector search.

GET /v1/breakouts

List videos currently breaking out among tracked creators.

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.

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 — NOT per-video AI analysis; for a hook and scene teardown of one of these videos, pass its URL to analyze_tiktok_video.

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 by URL. Consumes one catalog slot.

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 — call get_trend_search_result with that job_id until status is "completed", then read the results from that response.

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.

POST /v1/library

Save a video to the workspace library.

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.

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