Hook Detector

Read a YouTube Studio audience retention screenshot (base64 PNG or JPEG) into 100 points and the 21 marks it was read from (1 credit). Not the chart is 422 not_a_retention_chart, free. Same as POST /v1/review/graph.

New thumbnails for your video with a YouTube video's own thumbnail as the layout reference (2 to 4 images, every printed word checked); priced as make_thumbnails. Same as POST /v1/thumbnails/recreate; read it with get_thumbnails.

Owner only: reject a pending access request. Nothing is emailed. An approved or rejected request is 409 request_already_decided. Free.

Make it mine, for a long-form opening or a package: write up to n (1 to 5, default 3) new ones for your niche that keep one real find's structure. From a long find, `written` holds openings: hook (what the creator says first), then (what the next half minute has to deliver) and kept_structure, built on the find's template and its order of beats. From a packaging find it holds packages: title, thumbnail (what to show and how to frame it), thumbnail_text (the words to print, or null) and kept_structure, built on its title template and its thumbnail's composition. Write my intro: with mode "intro" and video_brief (your own video in a few sentences, 10 to 600 characters; a long find only, a packaging find is 422; niche and n are not used) it writes YOUR intro in the real opening's structure. `written` then holds one object with a beat for each beat of the real opening, in order: beat, does, from_s, to_s, seconds and words_budget (the real opening's own timing, never the model's), say (the words to say, with {placeholders} for what only you know), words, placeholders, suggested_on_screen and suggested_broll (suggestions, never part of what is said); and seconds, timing (measured or estimated), kept_structure, placeholders and numbers_to_placeholders. The answer carries mode "intro" and video_brief, and niche is null. A number you did not write in video_brief becomes {number}. One that copies the real opening or runs over a word budget is 422 remix_not_possible. Returns {"find_id", "kind", "niche", "n", "written", "label", "credits_charged": 1, "credits"}. label says they were written by Hook Detector from a real opening's (or package's) structure: show it with them, never present one as a real video's. One that is the real find's own words is dropped. They are never added to a run, a keep or an export. Costs 1 credit per call, taken before the model is asked and refunded when it…

Make it mine: write up to n new opening lines (1 to 5, default 3) for your niche that keep a real hook's structure, the device that made it travel, with the subject swapped for yours. hook_id is one of your hooks (from get_run, get_hook or list_keeps); 404 hook_not_found otherwise. Leave mode out: "intro" (Write my intro) is remix_find on a long-form find, and is 422 here, before any charge. Returns {"hook_id", "niche", "n", "written": [{"line", "kept_structure"}], "label", "credits_charged": 1, "credits"}. label is always "Written by Hook Detector from a real hook's structure": these are written lines, never found hooks; show the label with them, never present one as a real clip's hook. They are never added to a deck, a keep or an export. Costs 1 credit per call, taken before the model is asked and refunded when it does not answer (503 model_unavailable) or when nothing it wrote keeps the rules or it declines the content (422 remix_not_possible, the reason in the message; another try or another niche may work). 402 insufficient_credits at a balance of 0; limited per account per hour (429 rate_limited). Needs the research permission. The answer carries remix_id: list_remixes and get_remix read it back, free. Same as POST /v1/hooks/{hook_id}/remix.

Take one video out of a folder; the hook or find and its keep stay. Returns {"item_id", "removed": true}. Same as DELETE /v1/folders/{folder_id}/items/{item_id}. Free. Errors: 404 item_not_found (also on a second remove).

Take a channel off one of your trackers. Same as DELETE /v1/trackers/{tracker_id}/channels/{ref}.

The owner removes a member; anyone leaves with member_id "me". A removed member's next spend comes from their own balance, never the pool. The owner leaving with members is 409 team_has_members; alone it ends the team and returns the pool. Needs admin. Free. Same as DELETE /v1/team/members/{member_id}.

Rename a folder, change its description, or both. A name another folder on the tab already has is 409 folder_exists. Returns the folder. Same as PATCH /v1/folders/{folder_id}. Free.

Ask for the beta access code a new account needs (create_account's access_code). email is where the code is sent; note is optional (who you are, up to 500 characters). The owner approves the request and the code is emailed at once; it works once, in any agent or on the web. Returns status pending (waiting for approval) or emailed (sent now). No key needed. Limited to 5 per address per hour. Free.

Keyword research for YouTube. volume: always estimated (YouTube publishes no search counts): estimated_monthly_searches with a range, a 0 to 100 score and band, its source (Google Trends with the YouTube filter against fixed anchors; or, when Trends is busy, YouTube autocomplete and the top results' views) and basis. competition: 0 to 100 counted from the top 10 long-form results (big channels, posted in the last year, the keyword in the title, how many beat their own channel 2x). score: value 0 to 100 (60% volume, 40% the room competition leaves), band very_low, low, medium, high or very_high (vidIQ's brackets) and the basis naming its inputs. related, questions, rising: terms from autocomplete and the top results' titles, each with its source. Costs 2 credits, refunded when the read fails; a bad request is 422 and costs nothing. Takes about 10 to 30 seconds. Same as POST /v1/keywords. Read it back with get_call.

Edit Review of a cut before upload (25 credits; an unlisted or public YouTube link up to 60 minutes): cuts a minute, long shots, dead air, sound changes, on-screen text, and the notes as Premiere CSV, Resolve EDL and FCPXML markers. Runs as a job. Same as POST /v1/review/edit; to review the file itself (when YouTube refuses our servers the link is refused free with upload_instead), send it to POST /v1/review/edit/upload.

Hook Review of your own opening (3 credits): a YouTube link (its first minute heard by Scribe v3) or a pasted script, scored out of 10 from named counted parts, a verdict per beat, and the promise check against your title and thumbnail words. Same as POST /v1/review/hook.

Script Review (3 credits): your pasted script read like a Video Review on estimated times, plus machine-sounding lines and a fact-check list. Runs as a job. Same as POST /v1/scripts/review.

Rate my Reel or Short: read one public short the way Hook Detector reads a clip (its first frames, its words heard by ElevenLabs Scribe v3) and rate it against the real finds on its subject (the Short form search over the last 30 days, ranked by their multiple over the creator's usual). Returns review_id, url, platform, video_id, subject, subject_from, clip (first_line, first_word_s, words_per_minute, longest_pause_s, words, heard_by, not_heard_why, onscreen_text, plays, multiple), reads (five, in order: stop, gap, momentum, feeling, reach; each with verdict strong, moderate or weak, says, computed_from counted against the finds, and finds: 1 to 3 ids from `finds`), finds (each a real video with its url, plays, multiple, first_line and pace), finds_from, label, credits_charged and credits. Never a guessed number. Costs 3 credits, taken first and given back on any failure: 422 invalid_link (before any charge), 404 video_not_found (private or removed), 422 not_a_short, 422 review_not_possible (too few finds on the subject), 503 model_unavailable. 402 insufficient_credits under 3; limited per account per hour (429). Takes up to about 90 seconds. Needs research. Same as POST /v1/review/short.

Video Review of any public long video (15 credits): five ranked fixes with times and the counted fact behind each, six sub-scores each with what it is computed from, the hook scored and rewritten (labelled as written), the curve (YouTube's replay peaks, not retention; your Studio curve via graph_points; else predicted, not measured), the story with gap rules, pace and loudness per section, the next five uploads. Runs as a job: answers the paid call (pending); get_call reads it. Same as POST /v1/review.

Owner only: revoke an access code (code_id from list_access_codes). It admits nobody from now on; accounts it already made keep working. 404 access_code_not_found for an unknown id. Free.

Revoke one of your API keys at once: key_id from list_keys, or "original" for the signup key. Any key may revoke itself (the result says so, and that key stops working immediately); revoking another needs admin. Never the last active key on the account (409): create another with create_key first. If a key leaked, pass key_id "others": every key of the account except the one you are calling with is revoked at once, and the result says how many (revoked_count) and which key is kept. Needs admin. Free.

Revoke an open invite: its link stops working at once. Owner only. Needs admin. Free. Same as DELETE /v1/team/invites/{invite_id}.

Check a saved search now, as a job (read it with get_job). 1 credit. Same as POST /v1/alerts/{alert_id}/run.

Save filters under a name for one tab: "long", "packaging" or "library" (the bounds are those of find_packaging's filters; a library preset may also hold min_comments, max_comments, posted_within_days and language). The same name on the same tab replaces it. Start a run from it with preset_id on find_long_hooks or find_packaging. At most 50 an account. Same as POST /v1/presets. Free.

File one video in a folder of its tab: a find (find_id) or any public YouTube video (video_id) in a long or packaging folder, a hook (hook_id) in a short one, with an optional note. A video already in the folder (the same find, another run's find of it, the same hook) returns that item with created false; a note given then replaces its note. Filing does not keep it. Same as POST /v1/folders/{folder_id}/items. Free. Errors: 404 find_not_found or hook_not_found, 422 kind_mismatch, 409 folder_full (2000 items).

Score a package against the real outliers on its subject, part by part (title device, length, words on the picture, faces, the words' role, contrast, brightness): each part says how many outliers it matches; pattern_match (0 to 100) is the mean share: how much the package resembles the subject's outliers, never a click-through rate or a prediction (in our test it scored outliers above their channels' usual videos on about 3 of 4 pairs). Also nearest (5 outliers) and fixes. 1 credit, refunded when the read fails. Same as POST /v1/packaging/score.

Channels by name or handle: the shared index first, then YouTube's own channel search. Free. Same as GET /v1/channels/search.

Search the shared index of public YouTube videos Hook Detector's runs measured, with no run: words by text and meaning, or browse; filters for the multiple, views, long or short, recency, channel size and language. Free. Same as GET /v1/index/search.

Thumbnails in the shared index by what the picture shows (q), or like a picture (image_url: read once by the model as subject, action, words and setting, then searched). Each result has matched_by (text or meaning). Free; image reads at most 60 an hour. Same as GET /v1/index/thumbnails and POST /v1/index/thumbnails/by-image.

Set a member's monthly cap on the pool (null removes it). A run started near the cap holds only what is left, so the cap is never passed mid-run (403 team_cap_reached below a run's minimum or a tool's price). Owner only. Needs admin. Free. Same as PATCH /v1/team/members/{member_id}.

Turn on a folder's share link: share_url is a public read-only page anyone with it opens signed out (hookdetector.com/f/<token>); api_url is the same as JSON (get_shared_folder). It shows the folder's name, description and items with their notes, never anything about the account. A shared folder keeps its link. Same as POST /v1/folders/{folder_id}/share. Free.

Share a finished Short form run as a public, read-only page anyone can open with the link, no sign-in: each hook's spoken line, on-screen words, idea, plays, creator and its video, in the Hook Detector skill page layout. Nothing about the account is on it. Returns {"run_id", "token", "url"}; give the person the url (https://hookdetector.com/p/<token>). Idempotent: a run keeps one link, so calling again returns the same url. The same body as POST /v1/runs/{run_id}/share; the page's data is GET /v1/shared/{token}, no key needed. Needs the write scope. Free. Errors: 404 run_not_found, 409 run_not_finished while the run works (call get_run with wait_seconds=50 first), 409 run_not_shareable for a failed run or a Long form or Packaging run, 422 invalid_request for a malformed run_id.

Real hooks this service has delivered, for a wait screen: talking heads only, each hook_id, still_url (a JPEG, no key needed), platform, creator, views and line (the banner on the video, else its opening line). The most viewed first, one per creator, only what is already public on TikTok or Instagram: never a topic, an account or a run. No key needed. Cached 10 minutes. Free. REST: GET /v1/showcase?n=12.

Channels in the shared index closest to this one by the meaning of their titles, else by shared words, with a similarity 0 to 1. Free. Same as GET /v1/channels/{ref}/similar.

Start a background job on Hook Detector's job runner. Only echo can be started by hand: it waits `seconds` and answers `message` back with how many attempts it took (a job survives a deploy). At most 3 an hour per account. Free. Same as POST /v1/jobs; read it back with get_job.

Your swipe file: the title structures of the Packaging finds you kept or filed, each title_template with its title_device, count (how many of those videos use it, one a video) and best (the example with the highest outlier_score, 0 to 100). The most used first; packages is how many videos were read, skipped how many had no structure. Same as GET /v1/swipe. Free.

Send one signed test delivery now and read what your URL answered. Same as POST /v1/webhooks/{webhook_id}/test.

Where the eye is predicted to land on a thumbnail: the picture with a heatmap over it (PNG, base64), a 16 by 9 grid, the peak, the share in each third, the concentration and the share in YouTube's length corner. UNISAL (AUC 0.895 on MIT1003): faces draw it strongly, printed words less than people read them; a prediction, not a click-through rate. Free. Same as POST /v1/thumbnails/attention.

Your tracker alerts, newest first, with the unread count. Free. Same as GET /v1/trackers/alerts.

A tracker's channels' uploads, strongest first. Free. Same as GET /v1/trackers/{tracker_id}/feed.

Trending Shorts: the short videos (TikToks, Instagram Reels, YouTube Shorts) rising now on a subject, fastest first. Each item has video_id, platform, url, cover_url, creator, caption, plays, posted_at, age_hours, plays_per_hour (plays over the hours since posting, at least one), multiple and multiple_basis (plays over the creator's usual: the median of their latest videos, or TikTok likes per video; null when it could not be measured), creator_usual, duration_s, and spoken_hook with spoken_hook_from (the opening line when one of your own Short form runs delivered the video, or Scribe v3 heard it). At most 20 items, 2 per creator; a video with no post date is never listed. unavailable names a platform whose search did not answer. Free (credits_charged 0); the same subject, platform and window within 30 minutes is served from the cache, and fresh fetches are limited per account per hour (429 rate_limited). 503 search_unavailable when no platform answered. Needs read. Same as GET /v1/shorts/trending.

Turn a folder's share link off: the old link stops working at once; share_folder again makes a new one. Same as DELETE /v1/folders/{folder_id}/share. Free.

Change an agent's name or monthly budget, or pause it. Same as PATCH /v1/agents/{agent_id}.

Change a saved search: its words, line, frequency or email. Same as PATCH /v1/alerts/{alert_id}.

Rename a tracker, share it, change its alert lines, or turn its daily ideas on. Same as PATCH /v1/trackers/{tracker_id}.

Your credits and what you have spent: credits (balance now), spent_total, reserved_now (credits held by runs still in flight, refunded in part when they finish), runs_total, last_30_days (one entry per UTC day: date, runs, charged) and recent (your 20 newest runs). Same shape as GET /v1/usage. Free.

Badges for up to 50 YouTube videos at once, as the Chrome extension shows them on every card: views, the multiple over the channel's usual views (long against long uploads, Shorts against Shorts) with its band, and views per hour with its basis. Ids with no badge are in unread with why. Free. Same as GET /v1/videos/badges.

Everything the index knows about one video: the multiple, views per hour and its history, real tags, title and thumbnail changes, our reads, similar videos. Free. Same as GET /v1/videos/{video_id}/scorecard.

A video's views per hour and its history from the shared index (new, rising and tracked videos read hourly, the rest daily); a video the index lacks is read now. Free. Same as GET /v1/videos/{video_id}/stats.

What an invite joins, before accepting: the team's name, who invited you, its seats, when the link expires, and whether you are signed in with the invited email (null for an account with no email). Free. Same as GET /v1/team/invites/{token}.

Vote on a poll with the slot you picked, and an optional reason. One vote an account, never on your own or your team's poll. Answers the shares so far. Free. Same as POST /v1/polls/{poll_id}/vote.

A webhook's deliveries, newest first, with status and your URL's answers. Same as GET /v1/webhooks/{webhook_id}/deliveries.

Hook Creator (1 credit): an opening for your subject as beats with seconds counted from their words and a shot plan per line (said, shown, on screen, sound, delivery), labelled as written. Same as POST /v1/openings.