Hook Detector

A channel page: subscribers and totals, every recent long upload scored against the channel itself (outliers at 2x its median and over), and its momentum. Free. Same as GET /v1/channels/{ref}.

One chat conversation: its newest messages in order (role, content, run_id, created_at), a page of `limit`, with earlier_cursor for the older ones (null when the page reaches the first message), and the runs those messages hold, with their hooks, plus nullable language and country search picker settings. Same shape as GET /v1/conversations/{conversation_id}. Free. Errors: 404 conversation_not_found, 422 for an id that is not a UUID or a cursor this API did not issue.

One result of a long or packaging run with every field: the video, its numbers and the opening or the package analysis. find_id comes from a run's finds (get_run) or from list_kept_finds. Same shape as GET /v1/finds/{find_id}. Free. Errors: 404 find_not_found, 422 for an id that is not a UUID.

One of your folders and its items, newest filed first, limit 1 to 100 a page (page with next_cursor). Each item has item_id, note, thumbnail_url, title and the full hook or find object. Same as GET /v1/folders/{folder_id}. Free. Errors: 404 folder_not_found.

One hook with every field: its opening line, transcript, watch_url and the vertical player_url (null only for an unusable id or a photo post found before 2026-09-26; runs deliver single videos only). hook_id comes from get_run. Free.

One background job of this account. Same as GET /v1/jobs/{job_id}. Errors: 404 job_not_found for another account's job or an unknown id.

An Optimize call: the original's score and every new package so far. Same as GET /v1/optimize/{call_id}. Free.

One poll: yours with votes, shares, 95% intervals, the leader once the votes separate, the slots and the reasons; or one you voted on with its shares. Free. Same as GET /v1/polls/{poll_id}.

One remix you paid for (from remix_hook, remix_find or a chat turn), as its answer held it. Free. 404 remix_not_found for one that is not yours. Same as GET /v1/remixes/{remix_id}.

One research page: every claim with the first run's and the second run's numbers (each run a sample of different channels), n per run and per cell, shown_a and shown_b (over the sample bar), reproduced (true, false, or null for too few) and direction, plus measures naming what each number is computed from. 404 page_not_found for an unknown slug, 422 for a malformed one. No key needed; limited per address. Free. Same as GET /v1/findings/{slug}.

A research run: its status, progress, charge and every hook it produced. wait_seconds 0 to 50: wait up to that long for the run to finish, returning the moment it is done or failed. Use wait_seconds=50 and call again while status is "queued" or "running"; a fresh run needs about 3 or 4 such calls. progress has stage, message and updated_at, plus counts once the research reports them, preview (hooks written so far) while a running run holds one, and feed (the live research wall: up to 24 clips the run is working on, newest first, each key, platform, creator, views, state found|reading|talking|passed, thumb_url, a JPEG any <img> can load with no key, and line, the banner or opening words once the judges passed the clip) while it shows one, and on a Long form or Packaging run scan (the videos it is looking at: up to 60 tiles {v: YouTube video id, s: found|on_topic|off_topic|measured|beat| reading|ready|passed, x: multiple of the channel's usual or null}, oldest first, and lanes with found, on_topic, measured, beat, reading, ready; draw a tile from https://i.ytimg.com/vi/{v}/mqdefault.jpg; counts.measured and counts.beat are the numbers report.landscape ends on). Pass since with the last progress.updated_at to return on change or completion. It must be an ISO timestamp with a timezone (422 invalid_request otherwise). `hooks` is the deck (a person talking); `bonus` is always [] (removed 2026-10-08). Every hook has format and section (always "main"), and creator_country (TikTok only), place and place_country (null when unknown), banner (the title placed on the video, null when none) and match ("exact" or "close", a close match being a neighbouring subject delivered after the exact ones; null on runs with no language or country and on older hooks). Since 2026-10-04 the run carries understood (what the request was read to ask: subject, language, country, core, audience, neighbo…

A shared folder as anyone with its link sees it: name, description, kind, item_count and items (public fields and the owner's note), newest first, paged. No key needed; limited per address (429). A link never made or turned off is 404 shared_folder_not_found. Same as GET /v1/shared/folders/{token}. Free.

The skeleton of a long find's whole video, heard by Scribe v3: sections, re-hooks, open loops, payoffs, sponsor and call-to-action spans, the outro, the timed lines. Builds it once for 5 credits as a paid call (status pending; read it with get_call); after that answers the stored one free. Same as POST and GET /v1/finds/{find_id}/skeleton.

Your team, or team null: its name, pool (credits), seats, each member's name and role. The owner also sees every member's email, monthly cap and spend, open invites (never their links) and the newest 50 charges to the pool (who, what kind, credits, when; never what it was about). your_credits is your own balance, untouched while you are a member. Free. Same as GET /v1/team.

A thumbnails call: status, concepts and every image so far (url signed for 7 days, width, height, words, words_checked, cost_usd). Same as GET /v1/thumbnails/{call_id}. Free.

One tracker and its channels. Same as GET /v1/trackers/{tracker_id}.

Invite someone: returns link (and its token), a single-use page valid 7 days, shown here only, and emailed to that address (emailed true; when false, give the link to the person yourself). Someone signed in with Google must hold that email to accept. Owner only. Needs admin. Free. Same as POST /v1/team/invites.

Keep or reject a find (a long-form hook or a package): verdict is "keep" (default) or "reject", and the last verdict wins. The verdict is the video's on that tab: every find of the same video you have there carries it, so a later run that finds the video again shows it already kept. Kept videos come back from list_kept_finds, across all runs. Returns {"find_id", "verdict"}. Same as POST /v1/finds/{find_id}/decision. Free. Errors: 404 find_not_found.

Keep or reject a hook: verdict is "keep" (default) or "reject", and the last verdict wins. A reject may say why: reason is off_subject, weak_opening, wrong_language, low_quality, already_have or other, and note (up to 280 characters) your own words. Kept hooks come back from list_keeps, across all runs. Free.

Owner only: every access code, newest first, with code_id, code_prefix, email, note, source, max_uses, uses, expires_at, revoked_at, created_at and usable. Never the code itself. Free.

Owner only: every access request, newest first, optionally only one status (pending, approved, rejected). Each has request_id, email, note, status, code_id, code_prefix, created_at and decided_at. Never a code. Needs the admin scope and an admin account (403 admin_required otherwise). Free.

Your agents with their budgets and this month's spend. Free. Same as GET /v1/agents.

Your saved searches and their newest hits. Free. Same as GET /v1/alerts.

Your calls of priced tools, newest first; tool ("titles", ...) narrows. Same as GET /v1/calls. Free.

Your chat conversations, most recently active first, limit 1 to 100 (default 30) per page: conversation_id, title, created_at, updated_at, language, country and messages (the count). Nullable language/country are the saved search picker settings. Returns {"conversations": [...], "next_cursor"}; pass next_cursor back as cursor for more. Same shape as GET /v1/conversations. Next step: get_conversation. Free.

The index: every video your long and packaging runs found, across all runs, one entry a video on each tab (its newest read, with the keep or reject made on the video). Each is a full find object: the title and thumbnail_url as YouTube shows them, views, channel_median_views, outlier (views over the channel's usual) and outlier_score (0 to 100 on one fixed scale, so entries from different runs rank together), plus the analysis its run wrote. q (at most 120 characters) looks in the title, the channel, the hook as it was said, and what the thumbnail prints and shows, so a package can be found by its thumbnail ("red arrow", "before and after"). Returns {"finds", "count", "total" (every match, on any page), "next_cursor"}; pass next_cursor as cursor for the next page. Use it to search what you already paid for before starting a new run. Same as GET /v1/finds. Free. Errors: 422 for a kind, sort, tier, min_score, device or q that is not allowed. The bounds min_multiple to language (T3-FL) narrow the index on the server, as on GET /v1/finds; an entry that does not carry a bounded field is left out.

Your folders, the most recently changed first, each with item_count, up to 4 cover thumbnails and its share link when shared. With hook_id or find_id, each folder also has contains: the item id when it holds that video (any run's copy), else null. Returns {"folders": [...], "count"}. Same as GET /v1/folders. Free.

Title formats of the last 90 days with their median multiple, share over 1.5x, adoption and examples, ordered by the Wilson lower bound of that share (computed_from). Formats with at least 8 measured videos from 3 channels (each shows measured beside videos); include_small lists down to 3 from 2. Free. Same as GET /v1/formats.

This account's background jobs, newest first (tracker refreshes, alerts, reviews, echo): status, attempts, credits, result or error. Free. Same as GET /v1/jobs.

The hooks you kept with keep_hook, newest decision first, across all runs or within one run_id, limit 1 to 100 (default 100) per page. Returns {"kept": [...], "count": n on this page, "next_cursor"} with full hook objects; pass next_cursor back as cursor for more. Same shape as GET /v1/keeps. Free. Errors: 422 for a bad run_id or cursor.

The videos you kept with keep_find (long-form hooks and packages), newest decision first: one entry a video on each tab across all runs, or the kept finds of one run_id, limit 1 to 100 (default 100) per page. Returns {"kept": [...], "count": n on this page, "next_cursor"} with full find objects. Same shape as GET /v1/finds/keeps. Free. Errors: 422 for a bad kind, run_id or cursor.

Your API keys and what each may do. keys: key_id, name, prefix, created_at, last_used_at and current (true for the key making this call). access, per key_id: scopes, credit_limit, credits_used, expires_at and expired. scopes: the calling key's. The original signup key has key_id "original". The keys themselves are never shown again. Needs admin. Same shape as GET /v1/keys. Free.

The niche explorer: every niche reported, with its headline numbers. Free. Same as GET /v1/niches.

Your package votes, newest first, with their results so far. Free. Same as GET /v1/polls.

Your saved filter presets, the newest change first; tab ("long", "packaging", "library") narrows. Same as GET /v1/presets. Free.

The remixes you paid for from one hook (hook_id) or one find (find_id), newest first, each as its answer held it, with remix_id and created_at. Returns {"remixes": [...]}. Free. 404 hook_not_found or find_not_found for one that is not yours. Same as GET /v1/hooks/{hook_id}/remixes and GET /v1/finds/{find_id}/remixes.

The research findings counted from Hook Detector's shared index of public YouTube data: openings (which openings sit before a steeper or flatter first minute of YouTube's "most replayed" heatmap, replay intensity, not retention), title-devices (which title devices go with higher multiples, by niche) and title-thumbnail-overlap (title and thumbnail word overlap against the multiple). Each page with n per run and how many claims reproduced on a second sample of other channels, did not, or had too few videos. No key needed; limited per address (429). Free. Same as GET /v1/findings.

Your research runs, newest first, without their results, limit 1 to 100 (default 20) per page. Each run says its kind: "short" (find_hooks), "long" (find_long_hooks) or "packaging" (find_packaging); pass kind to list only one. Returns {"runs": [...], "next_cursor"}: pass next_cursor back as cursor for the next page; it is null on the last. Same shape as GET /v1/runs. Next step: open one with get_run, or download it with export_run. Free. Errors: 422 invalid_cursor for a cursor this API did not issue, 422 for a kind that is not one of the three.

The hook strategy library: every kind of long-form hook the shared index holds at least 3 openings of, with its plain name, count, the median multiple of those videos over their channels' usual views, the median hook length in seconds, the template most share, and up to 3 real examples (title, hook as said, video_id, channel, multiple). Counted from the index, never by a model; public data only. Free. Same as GET /v1/strategies.

Your trackers, or every public one. Free. Same as GET /v1/trackers.

Rising words and phrases in the shared index's titles, this window against the one before, with counts and growth. Free. Same as GET /v1/trends.

Your webhooks with their events and state (never the secret). Same as GET /v1/webhooks.

Real title and thumbnail changes on other channels: both versions (the pictures as URLs), views per hour before and 24 to 72 hours after, the lift and when the spike came. Free. Same as GET /v1/winners.

Make 2 to 12 thumbnails (default 4): 3 different concepts first, then images (Nano Banana 2.1, 1K or 4K), every printed word read back and checked letter by letter, a face only from your photos or your channel's own thumbnails. Answers at once with call_id and status pending; read it with get_thumbnails until done. 4 credits a delivered 1K image, 12 a 4K one, charged only for what is delivered. Same as POST /v1/thumbnails.

Move credits between your balance and the team's pool; 402 when the side giving holds less, and nothing moves. Owner only. Needs admin. Free. Same as POST /v1/team/credits.

A poll of another Hook Detector user waiting for your vote (not one you passed in skip): its options in an order of your own, no counts; poll null when none is waiting. Free. Same as GET /v1/polls/next.

A niche report counted from the shared index: videos, channels, median views, the share at 10x and over, the 75th percentile multiple, top outliers and channels, by month. Free. Same as GET /v1/niches/{slug}.

New packages (4, 8 or 12) for your published video: the original scored first against the real outliers on its subject, then each new package (title, thumbnail with every word checked, what it tests) scored the same way, best first, with vs_original. 10 credits a delivered package. Answers at once; read it with get_optimize. Same as POST /v1/optimize.

Your package in a mock YouTube feed among a run's winners: view home, search, sidebar, phone (marks where a phone cuts the title) or tv; theme dark or light; look normal, grey or blur. Returns png_base64 and mine_at. Free. Same as POST /v1/packaging/preview.

Outliers at random from the shared index (5x their channel's usual and over by default), a different set each call. Free. Same as GET /v1/index/random.