Hook Detector

Pack 2 or 3 images of one of your thumbnails, edit or Optimize calls for YouTube Studio's Test and Compare: a zip of A, B, C (1280x720, under 2 MB) and a note of what each tests. Free. Same as POST /v1/ab.

Join the team an invite names. From then on what you spend comes from the team's pool; your own runs stay private and your own balance waits for you. Each link works once (409 invite_used) for 7 days (410 invite_expired). Needs admin. Free. Same as POST /v1/team/invites/{token}/accept.

Add channels to one of your trackers. Same as POST /v1/trackers/{tracker_id}/channels.

Owner only: add or remove an account's credits, as POST /v1/admin/accounts/{account_id}/credits. A change that would take the balance below zero is 422 credits_below_zero and nothing changes; an unknown account is 404 account_not_found. Every change is audited (admin_list_actions). Returns {account_id, credits, delta}.

Owner only: every account, newest first, as GET /v1/admin/accounts: {total, accounts: [{id, email, name, label, credits, created_at, last_seen_at, runs, hooks, charged_total, is_admin, admitted_by, keys_active}]}. Free.

Owner only: the audit of password sign-ins and credit changes, newest first, as GET /v1/admin/actions: {actions: [{id, action, actor_email, target_account_id, detail, created_at}]}. Free.

Owner only: every account's research runs, newest first, as GET /v1/admin/runs: {runs: [{run_id, account_id, email, topic, language, country, status, requested, hooks, reserved, charged, failure_kind, error, created_at, finished_at}]}. Free.

Owner only: the whole service at a glance, as GET /v1/admin/overview. Counts of accounts and people; runs (total, last_24h, last_7d, failed_24h, in_flight); hooks; credits (charged_24h, charged_7d, charged_total, balance_total); access (pending_requests, active_codes, redemptions); search (credits_left, low, accepting_runs; null when not read yet); and the running commit. Needs the admin scope and an admin account (403 admin_required otherwise). Free.

Owner only: approve an access request. Makes a one-use code, marks the request approved and emails the code. The code is in this result once, with emailed true or false; when false, send it yourself or approve again (the unused code is revoked and a new one sent). 409 request_already_decided once its code was used. Free.

Your account and remaining credits right now: account_id, credits, key_prefix and key_id of the key making this call, label, created_at, and that key's scopes, credit_limit and expires_at, and user (the person signed in with Google, or null). Same shape as GET /v1/me. A run needs at least 40 credits and reserves up to 200. For spend, credits held by in-flight runs and daily history, call usage. Free.

A channel's own outliers (scope own), or outliers for a channel like it from other channels in the shared index (scope niche, 3x and over by default). Free. Same as GET /v1/channels/{ref}/outliers.

One conversational turn, for an agent relaying a person's words. It either asks ONE clarifying question (action "clarify"), answers about delivered hooks or the tool (action "answer", run null, no credits), or starts a research run (action "research", with the started run under "run"), exactly like POST /v1/chat. Every response has suggestions: 0 to 4 follow-ups, [] for research. A deck size typed into the message ("..., 15 hooks") and a recency phrase ("this month", "last week") set the run's count and posted_within_days; the count argument sets the deck size when the message states none. Asked to make one of the conversation's hooks yours for a niche ("make hook 2 mine for dentists"), the turn writes lines from that hook's structure (1 credit, like remix_hook) and answers them labelled, the full result under "remix". language and country select the search locale: omitted or null keeps the current conversation setting; a value sets it for this and later turns; an empty string clears it to any language / any country. The picker wins over the message's locale; replies stay in the language the person writes in. Invalid locale: 422 invalid_request. message is 1 to 4000 characters. Pass conversation_id from an earlier turn to keep the context; leave it out to start a conversation. Cost: a turn itself is free but is a model call, so turns are limited per account per hour (429 rate_limited); a turn that starts a run reserves credits like find_hooks. Next step: on "research", call get_run with run.run_id and wait_seconds=50. Errors: 503 model_unavailable when the model is down (nothing charged, try again), 402 insufficient_credits. For direct research without the question step, call find_hooks instead. Needs the write permission, and research for a turn that starts a run (403 insufficient_scope, nothing reserved).

The talking-head cleaner (15 credits), like 1of10's AutoCut: silences tightened, retakes, false starts, stutters and fillers cut with a reason on every cut, other microphones or cameras synced to the first, as Premiere XML, FCPXML and a CMX 3600 EDL. Takes 1 to 4 file_id values staged with POST /v1/clean/files (a chat cannot send the file itself). Runs as a job; get_call reads it. Same as POST /v1/clean.

Undo keep_hook: the hook goes back to having no verdict, so it leaves list_keeps and its export row carries none. Returns {"hook_id", "verdict": null}. Clearing a hook with no decision is the same success, so a retry is safe. Same as DELETE /v1/hooks/{hook_id}/decision. Free. Errors: 404 hook_not_found, 422 for an id that is not a UUID.

Undo keep_find: the video goes back to having no verdict, on every find of it, and leaves list_kept_finds. Returns {"find_id", "verdict": null}. Clearing a find with no decision is the same success, so a retry is safe. Same as DELETE /v1/finds/{find_id}/decision. Free.

Copy a public or shared tracker into a private one of yours. Same as POST /v1/trackers/{tracker_id}/clone.

End your poll now: no more votes, the votes so far kept with its results. Free. Same as POST /v1/polls/{poll_id}/close.

What a subject's audience asks and struggles with: the top comments of its outliers (videos that beat their own channel; or your video_ids, or a channel's best uploads), grouped into questions, pain points and requests. clusters: label, kind (question, pain_point, request, other), count (comments in the group, counted in code, never by the model), likes, videos, and quotes: two real comments found word for word, each with its link (url opens the comment). videos: what was read, with views, multiple (views over the channel's usual), comments_read and comments_off. basis says what the counts are from. Costs 3 credits, refunded when the read fails; a request naming nothing or two things is 422 and costs nothing. Takes about 60 to 100 seconds (measured 2026-10-26). Same as POST /v1/comments/insights. Read it back with get_call.

Owner only: make an access code to hand out. max_uses 1 to 100000 (default 1), expires_in_days 1 to 365 (optional), note your own. email binds it to one person: then only Google sign-in with that verified email redeems it, never the API or MCP; leave it out for a code that works on every door. The code is in this result only. Free.

Create an account and get an API key with free credits. Needs a beta access code (access_code, HD-XXXX-XXXX; case and dashes do not matter): without one the error is 403 access_code_required, and a code that does not work is 403 invalid_access_code. Ask for a code with request_access, or at hookdetector.com/access. No key needed for this call. label is an optional note up to 120 characters. Keep the api_key it returns: it is the only copy. Send it as the header 'Authorization: Bearer hd_...' or pass it as api_key on every other tool. Signups, and wrong codes, are limited per address per hour. Next step: find_hooks.

An agent that runs a Video Review on each new long upload of a tracker's channels, inside a monthly credit budget. Same as POST /v1/agents.

Save a search checked daily or weekly; a new video at your line (default 3x its channel) is a hit, emailed, with a Monday digest. 1 credit a check. Same as POST /v1/alerts.

Make a named folder on one tab to file hooks or finds in. The same name again on that tab (case and spaces aside) returns the folder already there with created false, so a retry never makes two. At most 200 folders an account (409 folder_limit_reached). Returns the folder: folder_id, kind, name, item_count, cover, shared, share_url, created. Same as POST /v1/folders. Free. Next: save_to_folder.

Create another API key on your account, for example one per agent or machine, so you can revoke one without touching the others. name is up to 60 characters. Give the key only what it needs. scopes: any of "read" (read runs, hooks, keeps, usage), "write" (keep, reject, undo, chat), "research" (start runs, which spend credits), "admin" (manage keys, delete the account); all four when left out. An agent that finds hooks needs ["read", "write", "research"]. credit_limit: the most credits runs started with this key may spend over its life, 1 to 100000 (a run then reserves at most what is left). expires_in_days: 1 to 365; the key then stops working (401 key_expired). The new key is in this result once and never again: store it now. Needs admin. An account holds at most 10 active keys (409 beyond) and may create 20 per hour by default (429 beyond). Free. Next step: use the returned api_key; revoke old ones with revoke_key.

Put 2 to 4 packages to Hook Detector's users, who pick the one they would click, blind. Closes at votes_wanted or after 7 days. 2 credits, given back when a picture cannot be stored. Results with get_poll. Same as POST /v1/polls.

Create a team this account owns, funding its pool from your balance with credits (402 when you hold less). Members' spending comes from the pool; you keep spending your own balance. 409 already_in_team. Needs admin. Free. Same as POST /v1/team.

Make a tracker of up to 50 channels: hourly reads of their newest uploads, alerts when one reaches the multiple (default 3x its channel) or views per hour, in the app and by email. 1 credit a tracked channel a day. Same as POST /v1/trackers.

Post every new tracker alert and saved-search hit to your https URL, signed with the secret this returns once (X-HD-Signature). Same as POST /v1/webhooks.

Your daily idea sets (turn them on per saved search or tracker with daily_ideas), each idea with the real finds behind it, none repeated within a week. Same as GET /v1/ideas/daily.

Erase your account and everything in it, for good: every API key, run, hook, keep or reject decision, conversation and message. Unspent credits go with it. It cannot be undone. confirm must be exactly "delete my account", or nothing happens (422 confirmation_required). Refused with 409 run_in_flight while a run is queued or running: wait for it with get_run first. Returns {"deleted": true, "account_id", "erased": {counts per kind}, "message"}. Every key of the account stops working at once; create_account starts a new one. Same as DELETE /v1/account. Free.

Delete one of your agents. Same as DELETE /v1/agents/{agent_id}.

Delete a saved search. Same as DELETE /v1/alerts/{alert_id}.

Delete a folder, its items and its share link at once (the link stops working). The hooks and finds in it, and their keeps, stay. Returns {"folder_id", "deleted": true}. Same as DELETE /v1/folders/{folder_id}. Free. Errors: 404 folder_not_found.

Delete your poll, its votes and its pictures. Free. Same as DELETE /v1/polls/{poll_id}.

Delete one of your presets. Same as DELETE /v1/presets/{preset_id}. Free. Errors: 404 preset_not_found.

Delete one of your trackers. Same as DELETE /v1/trackers/{tracker_id}.

Delete one of your webhooks. Same as DELETE /v1/webhooks/{webhook_id}.

Set the note on one item of a folder. Returns the item. Same as PATCH /v1/folders/{folder_id}/items/{item_id}. Free. Errors: 404 item_not_found.

Edit one thumbnail (an image of your thumbnails call, or a picture you send): op erase, edit, face_swap, text, text_variations, upscale, fix, crop or color. crop and color are free; upscale 12; the rest 4 (a version each for text_variations), charged only for what is delivered. Answers at once; read it with get_thumbnails. Same as POST /v1/thumbnails/edit.

Official TikTok or Instagram embed HTML for a hook, so the clip plays inside your own page. kind is "embed", or "fallback" when the creator disabled embedding or the clip is a photo post found before 2026-09-26 (then show thumbnail, which falls back to the hook's still_url, and the transcript). For a plain vertical iframe use the hook's player_url instead. Free.

A finished run's hooks as a file a creator can open: format "csv" (default; one row per hook, opens in any spreadsheet, formula-like cells defused with a leading quote), "json" (the full hook objects) or "md" (Markdown notes, one section per hook). Returns {"filename", "content_type", "format", "content"}, where content is the whole file as text: write it to filename. The same bytes as GET /v1/runs/{run_id}/export?format=... . Free. Errors: 404 run_not_found, 409 run_not_finished while the run is queued or running (call get_run with wait_seconds=50 first), 422 invalid_request for another format.

Start hook research on a topic across TikTok, Instagram and YouTube Shorts (Shorts only, never long-form YouTube; platform "youtube"). platforms (since 2026-10-10, any of "tiktok", "instagram", "youtube"; all three when left out) searches and delivers only those: ["instagram"] is Instagram reels only. What it does: searches both platforms, reads what each clip says and shows, and returns ranked hooks. Each hook has its verbatim opening line, most quotable line, main idea, why it travelled, topic, on-screen text, full transcript, a watch link and a vertical player_url (9:16 iframe). Talking heads only (since 2026-09-29): `hooks` holds only clips where a person on camera is talking (talking head, podcast, interview). A clip where nobody talks is dropped; Bonus was removed on 2026-10-08 and `bonus` is always []. Every hook carries format (talking_head, podcast, interview, stage; null on older hooks) and section (always "main"). A run that finds fewer talking heads than count says so in outcome; it never fills hooks with clips that do not talk. Where it comes from (since 2026-09-30): every hook has creator_country (ISO alpha-2 of the creator's TikTok account; always null on Instagram, which states none), place (the place the creator tagged, or null) and place_country (that place's country when the platform states it). Never guessed. Banner (since 2026-09-30): every hook has banner, the title-style text the creator placed on the video to hook the viewer, verbatim (at most 200 characters), or null when it has none; subtitles are never a banner. onscreen_text keeps all text read. Match (since 2026-09-30, runs with a language or country): every hook has match, "exact" when the clip is about the subject itself or "close" when it is about a neighbouring subject with the same intent (a close match, delivered after every exact match; label it as one); null on runs with no langu…

Find long-form hooks: how the YouTube videos that beat their own channel open, on a topic. Long-form YouTube only, never Shorts, TikTok or Instagram (for those: find_hooks). What it does: searches YouTube for long-form videos on the topic, keeps only the outliers (a video whose views are at least min_outlier times the median views of its own channel's recent uploads; 2 by default) posted in 2023 or later (nothing older is ever delivered), reads the first intro_seconds (60 by default) of each one's transcript, and says why that opening holds a viewer. What comes back: the run's `finds`, ranked, strongest outlier first. Each has title, channel, watch_url, player_url (an iframe src), thumbnail_url, views, channel_median_views, outlier (28.2 means 28 times the channel's usual), outlier_score (0 to 100 on one fixed scale: nothing else a run found moves it, so finds from different runs rank together), outlier_tier, channel_size, likes_per_1k, posted_at, duration_s, and the opening: intro (the first minute as it was said: lines of n, t in seconds, text) and intro_text, always whole; and inside it the hook (verbatim: the lines the analysis marks as the hook, ending on a sentence end, at most 25 seconds and 60 words, with hook_words, hook_start_s and hook_end_s, a sponsor read or greeting at the front left out; hook_seconds is hook_end_s). auto_captions says the opening has almost no punctuation. about_subject is yes or partly: a video the model judges not to be about the subject is dropped. The analysis: hook_type (the same list as find_hooks), mechanism (why it holds, quoting the opening word for word), promise, open_loop, title_link (how the first lines pay off the title), beats (the opening in parts: from, to, beat, does), opens_with (cold_open, greeting, teaser, question, sponsor), format (the kind of video), angle, template (the hook as a fill-in structure), steal_it and audi…

Find packaging: the titles and thumbnails that earned the click on a topic, from long-form YouTube videos that beat their own channel. What it does: runs the same outlier search as find_long_hooks (long-form YouTube, 2023 or later, views at least min_outlier times the channel's usual), then looks at each video's thumbnail beside its title and says what the pair is doing. What comes back: the run's `finds`, ranked. Each is a real package, as YouTube shows it: title (verbatim) and thumbnail_url (the size YouTube really served, the picture the analysis looked at; thumbnail_checked says so), channel, watch_url, views, channel_median_views, outlier, outlier_score (0 to 100 on one fixed scale, so finds from different runs rank together), outlier_tier, channel_size and posted_at, plus the analysis: title_device (curiosity_gap, contrarian_claim, specific_number, how_to, listicle, challenge, story, question, warning, comparison, authority, timeliness, identity_callout, other), title_template (the title as a fill-in structure), thumbnail_text (the words printed on the thumbnail, read by a vision model; null when none), thumbnail_text_role (repeats_title, adds_to_title, contrasts_title, no_text; counted from title_overlap, the share of the thumbnail's words that are also in the title, where that can be), thumbnail_subject, thumbnail_faces, thumbnail_emotion, thumbnail_colors, thumbnail_composition, thumbnail_devices, angle, gap (what the picture shows that the title does not say, and the question that leaves), promise, steal_it and audience, visible_action (the single thing happening in the picture), title_carries and picture_adds (what only the title says, what only the picture adds), text_box, and thumb_metrics (measured in code from the pixels: palette, brightness, contrast, saturation, busyness, the biggest words' height at 210 px wide and whether the length corner is clear), plus cu…

The videos in the shared index nearest one of your finds (find_id from a Packaging or Long form run), nearest first, never the find's own video. Each has distance (0 is the same; measures says how it is computed), its numbers and its multiple over its channel's median. A find not indexed yet is matched by its own words (matched_from). Free. Same as GET /v1/finds/{find_id}/similar. Errors: 404 find_not_found.

Who sponsors the channels on a subject: in the descriptions of its outliers, sponsor lines, promo codes and offer links found in code, plus Scrape Creators' sponsor read of videos YouTube marks as paid promotion, each named by one model read and kept only when the brand's name is in its own line. sponsors: brand, kind (sponsor, affiliate, other), channel_count and video_count (counted in code), channels, and videos with the evidence line as written, the code and the link. Costs 1 credit, refunded when the read fails. Same as POST /v1/sponsors. Read it back with get_call.

One title format's videos, strongest first. Free. Same as GET /v1/formats/{format_id}.

One agent and its reviews (done, skipped or failed, and why). Same as GET /v1/agents/{agent_id}.

One saved search and its hits. Same as GET /v1/alerts/{alert_id}.

One call of a priced tool (titles and the tools after it): tool, credits, charged, status (pending, done, failed), request and result. Same as GET /v1/calls/{call_id}. Free. Errors: 404 call_not_found.