# Hook Detector > Real TikTok and Instagram hooks that already work, in any language, with why each travelled. - name: com.hookdetector/hookdetector - version: 2.4.0 - connection class: R0 (autonomous) - trust: 83/100 flags: no-repository - quality: 72/100 (needs work) - owner: not claimed - descriptor: https://api.protogrid.dev/v1/servers/com.hookdetector%2Fhookdetector - tools: https://api.protogrid.dev/v1/servers/com.hookdetector%2Fhookdetector/tools **An agent can connect right now, no human step.** Remote endpoint, no authentication, reachable on the last probe. ## Connection (mcpServers) ```json { "mcpServers": { "hookdetector": { "type": "http", "url": "https://api.hookdetector.com/mcp", "headers": { "Authorization": "Bearer ${HOOKDETECTOR_TOKEN}" } } } } ``` Placeholders to fill: `${HOOKDETECTOR_TOKEN}`. ## Trust - hygiene: 80 - liveness: 100 - freshness: 100 - provenance: 55 - drivers: +dns-namespace +website +reachable +uptime-99% +updated-25d-ago -no-repository - Derived from observable signals (official registry feed and our own credential-free probes); no code audit performed. ## Quality 72/100 (needs work) ### protocol: 88 (weight 25) - pass `protocol.modern`: supports 2026-07-28 (server/discover) - pass `protocol.stateless`: answers without a session - pass `protocol.transport`: streamable HTTP - warn `protocol.list_ttl`: tools/list declares ttlMs 0, so clients re-fetch it on every use ### authorization: n/a (weight 15) - n/a `auth.prm`, `auth.as_metadata`, `auth.cimd`: no remote uses OAuth - n/a `auth.secret_in_url`: no templated URL ### tool hygiene: 57 (weight 30) - pass `tools.descriptions`: every tool has a description - warn `tools.description_length`: 7 tools have descriptions over 1,024 characters, which crowds the context - pass `tools.schemas`: every tool has an object input schema - fail `tools.annotations`: no tool declares readOnlyHint or destructiveHint, so clients cannot tell safe calls from risky ones - fail `tools.directory_hints`: no tool declares all four of readOnlyHint, destructiveHint, idempotentHint and openWorldHint; missing: find_hooks (readOnlyHint, destructiveHint, idempotentHint, openWorldHint); get_run (readOnlyHint, destructiveHint, idempotentHint, openWorldHint); list_conversations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint); … - warn `tools.token_cost`: about 18,271 tokens to load every tool - pass `tools.api_dump`: tools are not a one-to-one API dump ### stability: 75 (weight 15) - warn `stability.changes`: 64 tool changes in 30 days - pass `stability.rug_pull`: no tool changed its meaning under the same name ### dependencies: n/a (weight 15) - n/a `deps.known_vulns`, `deps.mcp_sdk_version`, `deps.resolvable`: no npm or PyPI package - tools: 43, about 18,271 tokens to load them all - tool set hash: 710b89aa782770b14b20b6411c453e77 - tools last changed: 2026-10-12T20:18:32.054Z - badge: [![protogrid quality](https://protogrid.dev/badge/com.hookdetector/hookdetector.svg)](https://protogrid.dev/servers/com.hookdetector/hookdetector) - Checks run on what our credential-free, read-only probes observe; tools are never called and no code audit is performed. ### Tool changes - 2026-10-12 `keep_hook` changed (description, inputSchema) - before: Keep or reject a hook: verdict is "keep" (default) or "reject", and the last verdict wins. Kept hooks come back from list_keeps, across all runs. Free. - after: 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. - 2026-10-12 `get_run` changed (description) - before: 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 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, neighbours, styles, style_other, wants; null until read) and, on a run that asked for a kind of opening ("controversial hooks", "storytime"), every hook carries style_match (true when it opens that way; null otherwise). Since 2026-10-01 every hook carries the virality v2 fields: virality (0 to 1 on one fixed scale since 2026-10-02), virality_why, outlier, outlier_basis, creator_median_views, posted_at, age_days, views_per_day, duration_s, paid, sound_reuse, own_sound, hashtags (null on older hooks), and since 2026-10-02 the analysis: hook_type, hook_type_other, mechanism, visual_hook, audience, template, steal_it; the run echoes posted_within_days and seed_hook_ids, and once done carries patterns: up to 5 hook structures winning in this deck, each name, template, why, hook_ids and count, grouped by hook_type and computed before the run is done, in the deck's language (null on older runs and when nothing is shared). Hooks include transcript_kind: speech, music, none, other, or null when unknown. conversation_id names the chat conversation the run belongs to (null outside one). A done run with fewer hooks than asked for, or none, has outcome: why in one plain paragraph, what to try next, and whether it was free (stats.rejections holds the counts); a full run's outcome is null, or one sentence when some hooks are under the view floor because the country filter set clips aside. Free: reading a run costs no credits. - after: 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 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, neighbours, styles, style_other, wants; null until read) and, on a run that asked for a kind of opening ("controversial hooks", "storytime"), every hook carries style_match (true when it opens that way; null otherwise). Since 2026-10-01 every hook carries the virality v2 fields: virality (0 to 1 on one fixed scale since 2026-10-02), virality_why, outlier, outlier_basis, creator_median_views, posted_at, age_days, views_per_day, duration_s, paid, sound_reuse, own_sound, hashtags (null on older hooks), and since 2026-10-02 the analysis: hook_type, hook_type_other, mechanism, visual_hook, audience, template, steal_it; the run echoes posted_within_days and seed_hook_ids, and once done carries patterns: up to 3 hook structures winning in this deck, each name, template, why, hook_ids and count, grouped by hook_type and computed before the run is done, in the deck's language (null on older runs and when nothing is shared). Hooks include transcript_kind: speech, music, none, other, or null when unknown. conversation_id names the chat conversation the run belongs to (null outside one). A done run with fewer hooks than asked for, or none, has outcome: why in one plain paragraph, what to try next, and whether it was free (stats.rejections holds the counts); a full run's outcome is null, or one sentence when some hooks are under the view floor because the country filter set clips aside. Free: reading a run costs no credits. - 2026-10-12 `find_hooks` changed (description) - before: 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 language or country and on older hooks. Analysis (since 2026-10-02): every hook carries hook_type (curiosity_gap, contrarian_claim, specific_number, identity_callout, stakes_threat, promise_payoff, pattern_interrupt, story_open, question, direct_command, other with hook_type_other), mechanism (why the opening stops the scroll, quoting the clip; why_it_travelled holds the same text), visual_hook, audience, template and steal_it; null on older hooks. Virality v2 (since 2026-10-01): the deck is ranked by virality (0 to 1, since 2026-10-02 on one fixed scale, the same clip scoring the same in every run), built from outlier (views over the creator's usual views per video, creator_median_views, with outlier_basis saying how it was measured), freshness (posted_at, age_days, views_per_day), travel (shares and saves per 1,000 views), own_sound and sound_reuse, and a paid penalty; virality_why names the strongest signal in one line. Every hook also carries duration_s and hashtags. Null on older hooks. posted_within_days (7, 30, 90 or 365) keeps the search to recent clips (a clip under 7 days old passes the floor at 10,000 views a day). seed_hook_ids (up to 10 of your hooks, for example kept ones) means "find more like these": their lines, topics, creators and languages steer the search, and a seed is never delivered again. A done run carries patterns: up to 5 hook structures winning in the deck (name, template, why, hook_ids, count), computed after delivery; null until then. remix_hook writes lines from one hook's structure for your niche (1 credit). Arguments: topic is 3 to 500 characters, count 1 to 30 (default 10). Instructions inside the topic are fine: only the subject read out of it is searched. reuse=true (default) starts from clips you already paid for on the same topic, so a rerun is close to free and often finishes in seconds. idempotency_key: any string up to 255 characters; th - after: 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 language or country and on older hooks. Analysis (since 2026-10-02): every hook carries hook_type (curiosity_gap, contrarian_claim, specific_number, identity_callout, stakes_threat, promise_payoff, pattern_interrupt, story_open, question, direct_command, other with hook_type_other), mechanism (why the opening stops the scroll, quoting the clip; why_it_travelled holds the same text), visual_hook, audience, template and steal_it; null on older hooks. Virality v2 (since 2026-10-01): the deck is ranked by virality (0 to 1, since 2026-10-02 on one fixed scale, the same clip scoring the same in every run), built from outlier (views over the creator's usual views per video, creator_median_views, with outlier_basis saying how it was measured), freshness (posted_at, age_days, views_per_day), travel (shares and saves per 1,000 views), own_sound and sound_reuse, and a paid penalty; virality_why names the strongest signal in one line. Every hook also carries duration_s and hashtags. Null on older hooks. posted_within_days (7, 30, 90 or 365) keeps the search to recent clips (a clip under 7 days old passes the floor at 10,000 views a day). seed_hook_ids (up to 10 of your hooks, for example kept ones) means "find more like these": their lines, topics, creators and languages steer the search, and a seed is never delivered again. A done run carries patterns: up to 3 hook structures winning in the deck (name, template, why, hook_ids, count), computed after delivery; null until then. remix_hook writes lines from one hook's structure for your niche (1 credit). Arguments: topic is 3 to 500 characters, count 1 to 30 (default 10). Instructions inside the topic are fine: only the subject read out of it is searched. reuse=true (default) starts from clips you already paid for on the same topic, so a rerun is close to free and often finishes in seconds. idempotency_key: any string up to 255 characters; th - 2026-10-10 `chat` changed (inputSchema) - 2026-10-10 `find_hooks` changed (description, inputSchema) - before: Start hook research on a topic across TikTok, Instagram and YouTube Shorts (Shorts only, never long-form YouTube; platform "youtube"). 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 language or country and on older hooks. Analysis (since 2026-10-02): every hook carries hook_type (curiosity_gap, contrarian_claim, specific_number, identity_callout, stakes_threat, promise_payoff, pattern_interrupt, story_open, question, direct_command, other with hook_type_other), mechanism (why the opening stops the scroll, quoting the clip; why_it_travelled holds the same text), visual_hook, audience, template and steal_it; null on older hooks. Virality v2 (since 2026-10-01): the deck is ranked by virality (0 to 1, since 2026-10-02 on one fixed scale, the same clip scoring the same in every run), built from outlier (views over the creator's usual views per video, creator_median_views, with outlier_basis saying how it was measured), freshness (posted_at, age_days, views_per_day), travel (shares and saves per 1,000 views), own_sound and sound_reuse, and a paid penalty; virality_why names the strongest signal in one line. Every hook also carries duration_s and hashtags. Null on older hooks. posted_within_days (7, 30, 90 or 365) keeps the search to recent clips (a clip under 7 days old passes the floor at 10,000 views a day). seed_hook_ids (up to 10 of your hooks, for example kept ones) means "find more like these": their lines, topics, creators and languages steer the search, and a seed is never delivered again. A done run carries patterns: up to 5 hook structures winning in the deck (name, template, why, hook_ids, count), computed after delivery; null until then. remix_hook writes lines from one hook's structure for your niche (1 credit). Arguments: topic is 3 to 500 characters, count 1 to 30 (default 10). Instructions inside the topic are fine: only the subject read out of it is searched. reuse=true (default) starts from clips you already paid for on the same topic, so a rerun is close to free and often finishes in seconds. idempotency_key: any string up to 255 characters; the same key within 24 hours returns the first run instead of starting and paying for a second one, so always pass one and reuse it when you retry. wait_seconds 0 to 50: - after: 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 language or country and on older hooks. Analysis (since 2026-10-02): every hook carries hook_type (curiosity_gap, contrarian_claim, specific_number, identity_callout, stakes_threat, promise_payoff, pattern_interrupt, story_open, question, direct_command, other with hook_type_other), mechanism (why the opening stops the scroll, quoting the clip; why_it_travelled holds the same text), visual_hook, audience, template and steal_it; null on older hooks. Virality v2 (since 2026-10-01): the deck is ranked by virality (0 to 1, since 2026-10-02 on one fixed scale, the same clip scoring the same in every run), built from outlier (views over the creator's usual views per video, creator_median_views, with outlier_basis saying how it was measured), freshness (posted_at, age_days, views_per_day), travel (shares and saves per 1,000 views), own_sound and sound_reuse, and a paid penalty; virality_why names the strongest signal in one line. Every hook also carries duration_s and hashtags. Null on older hooks. posted_within_days (7, 30, 90 or 365) keeps the search to recent clips (a clip under 7 days old passes the floor at 10,000 views a day). seed_hook_ids (up to 10 of your hooks, for example kept ones) means "find more like these": their lines, topics, creators and languages steer the search, and a seed is never delivered again. A done run carries patterns: up to 5 hook structures winning in the deck (name, template, why, hook_ids, count), computed after delivery; null until then. remix_hook writes lines from one hook's structure for your niche (1 credit). Arguments: topic is 3 to 500 characters, count 1 to 30 (default 10). Instructions inside the topic are fine: only the subject read out of it is searched. reuse=true (default) starts from clips you already paid for on the same topic, so a rerun is close to free and often finishes in seconds. idempotency_key: any string up to 255 characters; th - 2026-10-09 `remix_hook` changed (description, inputSchema) - before: 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. 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. - after: 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. - 2026-10-09 `remix_find` changed (description, inputSchema) - before: 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. 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 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; 404 find_not_found; 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/finds/{find_id}/remix. - after: 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 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; 404 find_not_found; 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/finds/{find_id}/remix. - 2026-10-09 `find_packaging` changed (description, inputSchema) - before: 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), 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. analysed is false when a package could not be looked at; it is still a real package. The run's report then holds title_patterns and thumbnail_patterns (what at least two of the packages share, each naming their video_ids) and ideas: up to `ideas` (6 by default, 0 for none) packages WRITTEN for your topic from those patterns, each a title a thumbnail concept and thumbnail_text (the words to print on it), naming the real packages it is based_on. report.ideas_label is always "Written by Hook Detector from the patterns in these real packages": show it with them, never present an idea as a real video's title. report.numbers counts the packages: title_chars and title_words (medians), titles_with_number, titles_with_question, thumbnails_with_text and thumbnail_words (over the analysed ones), and the title_devices, thumbnail_devices and emotions that repeat (name, count). report.landscape is the subject at a glance, as on find_long_hooks. Arguments: topic 3 to 500 characters, or a channel's or a long-form video's YouTube address exactly as on find_long_hooks (a channel's own outliers, or that one video; no ideas are written for a link, use remix_find); count 1 to 24 (default 12); language, country, min_outlier, posted_within_days, channel_size and reuse as on find_long_hooks; idempotency_key and wait_seconds as on find_hooks. Cost: reserves up to 70 credits (down to 25) and charges only the provider calls it made: the searches, one call per channel measured, and one for each video whose date had to be read exactly. Looking at a thumbnail costs no credit. After a find_long_hooks run on the same topic it is close to free. A failed run costs nothing, and so does a run that finds nothing, inside the allowance. Timing and next step: how long a run takes has not been measured yet, so never assume a time. Call get_run with wait_seconds=50 until status is done or failed. Same as POST /v1/packaging. Needs the research permission. - after: 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, plus cut_on_phone (the title is longer than 60 characters, where a phone roughly cuts it; approximate) and on_subject (yes or partly: whether the look judged the package to be about your topic; a package judged not to be is dropped and the next one takes its slot; null on a link run). analysed is false when a package could not be looked at (its look is asked twice, and the next candidate takes the slot if it fails twice); it is still a real package. The run's report then holds title_patterns and thumbnail_patterns (what at least two of the packages share, each naming their video_ids) and ideas: up to `ideas` (6 by default, 0 for none) packages WRITTEN for your topic from those patterns, each a title a thumbnail concept and thumbnail_text (the words to print on it), naming the real packages it is based_on. report.ideas_label is always "Written by Hook Detector from the patterns in these real packages": show it with them, never present an idea as a real video's title; an idea over 70 characters, with more than 5 words for its thumbnail or repeating a real title is dropped. report.numbers counts the packages: title_chars and title_words (medians), titles_with_number, titles_with_question, titles_cut_on_phone (with phone_title_chars, the approximate length a phone cuts a title at), thumbnails_with_text and thumbnail_words (over the analysed ones), and the title_devices, thumbnail_devices and emotions that repeat (name, count); age_cohorts repeats the counts for packages posted in the last split_days days (recent) and for older ones, with the undated apart. report.landscape is the subject at a glance, as on find_long_hooks. Arguments: topic 3 to 500 characters, or a channel's or a long-form video's YouTube address exactly as on find_long_hooks (a channel's own outliers, or that one video; no ideas are written for a link, use remix_find); count 1 to 30 (default 12); language, country, min_outlier, posted_within_days, channel_size and reuse as on find_long_hooks; idempotency_key and wait_seconds as on find_hooks. Cost: reserves up to 70 credits for 24 packages or fewer and 3 more for each package above that (88 at 30; down to 25) and charges only the provider calls it made: the searches, one call per channel measured, and - 2026-10-09 `find_long_hooks` changed (description, inputSchema) - before: 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: hook (the lines that stop a viewer leaving, verbatim), hook_seconds, intro (the first minute as it was said: lines of n, t in seconds, text) and intro_text. 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 audience. When the topic asks for a kind of opening ("question hooks", "storytime"), style_match says whether each find is that kind and the matches come first. analysed is false when the model could not analyse an opening: the opening is still real, its analysis fields are null. The run's report.patterns lists the opening types at least two finds share; report.shape says how the openings are built, counted from the finds (hook_seconds and hook_words as medians, beats with how many openings use each and the second it usually starts_at, and the sequence of beats most of them share); and report.openers holds up to `openers` (3 by default, 0 for none) openings WRITTEN for your topic from those structures (hook, then, hook_type, based_on). report.openers_label is always "Written by Hook Detector from the structure of these real openings": show it with them, never present one as a real video's opening. report.landscape is the subject at a glance, counted from the videos the run held against their own channel (videos, channels, outliers and their share, breakouts, small_channel_outliers, recent_outliers). The run's hooks and bonus are always empty. A link instead of a subject: when topic is a channel's YouTube address (https://www.youtube.com/@name, or just @name) the run returns that channel's OWN outliers, its recent long-form uploads that beat its usual (one provider call, no search); when it is a long-form video's address the run returns that one video, whatever its multiple (requested is 1). options.link says "channel" or "video". No openings are written for a link (use remix_find on a find to write for your niche). A Short's address is refused with 422. Arguments: topic 3 to 500 characters; count 1 to 20 (default 8); language and country optional; posted_within_days 30, 90, 365 or 730 to narrow the 2023 floor further; channel_size "small", "medium" or "large" to keep only channels of that size (by what their uploads usually get), so a small creator sees breakouts from channels their own size; reuse=true (default) starts from the videos your last long or packaging run on this topic bought within a week, and a video you already had read is delivered from that read (analysis_from_earlier_read) at no model or provider cost. seen_before - after: 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 audience. When the topic asks for a kind of opening ("question hooks", "storytime"), style_match says whether each find is that kind and the matches come first. analysed is false when the model could not analyse an opening: the opening is still real, its analysis fields are null. The run's report.patterns lists the opening types at least two finds share; report.shape says how the openings are built, counted from the finds (hook_seconds, how long the hook runs, and hook_words as medians, beats with how many openings use each and the second it usually starts_at, and the sequence of beats most of them share); and report.openers holds up to `openers` (3 by default, 0 for none) openings WRITTEN for your topic from those structures (hook, then, hook_type, based_on). report.openers_label is always "Written by Hook Detector from the structure of these real openings": show it with them, never present one as a real video's opening. report.landscape is the subject at a glance, counted from the videos the run held against their own channel (videos, channels, outliers and their share, breakouts, small_channel_outliers, recent_outliers). The run's hooks and bonus are always empty. A link instead of a subject: when topic is a channel's YouTube address (https://www.youtube.com/@name, or just @name) the run returns that channel's OWN outliers, its recent long-form uploads that beat its usual (one provider call, no search); when it is a long-form video's address the run returns that one video, whatever its multiple (requested is 1). options.link says "channel" or "video". No openings are written for a link (use remix_find on a find to write for your niche). A Short's address is refused with 422. Arguments: topic 3 to 500 characters; count 1 to 30 (default 8); language and country optional; posted_within_days 30, 90, 365 or 730 to narrow the 2023 floor further; channel_size "small", "mediu - 2026-10-09 `get_run` changed (description) - before: 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 can load with no key, and line, the banner or opening words once the judges passed the clip) while it shows one. 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, neighbours, styles, style_other, wants; null until read) and, on a run that asked for a kind of opening ("controversial hooks", "storytime"), every hook carries style_match (true when it opens that way; null otherwise). Since 2026-10-01 every hook carries the virality v2 fields: virality (0 to 1 on one fixed scale since 2026-10-02), virality_why, outlier, outlier_basis, creator_median_views, posted_at, age_days, views_per_day, duration_s, paid, sound_reuse, own_sound, hashtags (null on older hooks), and since 2026-10-02 the analysis: hook_type, hook_type_other, mechanism, visual_hook, audience, template, steal_it; the run echoes posted_within_days and seed_hook_ids, and once done carries patterns: up to 5 hook structures winning in this deck, each name, template, why, hook_ids and count, grouped by hook_type and computed before the run is done, in the deck's language (null on older runs and when nothing is shared). Hooks include transcript_kind: speech, music, none, other, or null when unknown. conversation_id names the chat conversation the run belongs to (null outside one). A done run with fewer hooks than asked for, or none, has outcome: why in one plain paragraph, what to try next, and whether it was free (stats.rejections holds the counts); a full run's outcome is null, or one sentence when some hooks are under the view floor because the country filter set clips aside. Free: reading a run costs no credits. - after: 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 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, neighbours, styles, style_other, wants; null until read) and, on a run that asked for a kind of opening ("controversial hooks", "storytime"), every hook carries style_match (true when it opens that way; null otherwise). Since 2026-10-01 every hook carries the virality v2 fields: virality (0 to 1 on one fixed scale since 2026-10-02), virality_why, outlier, outlier_basis, creator_median_views, posted_at, age_days, views_per_day, duration_s, paid, sound_reuse, own_sound, hashtags (null on older hooks), and since 2026-10-02 the analysis: hook_type, hook_type_other, mechanism, visual_hook, audience, template, steal_it; the run echoes posted_within_days and seed_hook_ids, and once done carries patterns: up to 5 hook structures winning in this deck, each name, template, why, hook_ids and count, grouped by hook_type and computed before the run is done, in the deck's language (null on older runs and when nothing is shared). Hooks include transcript_kind: speech, music, none, other, or null when unknown. conversation_id names the chat conversation the run belongs to (null outside one). A done run with fewer hooks than asked for, or none, has outcome: why in one plain paragraph, what to try next, and whether it was free (stats.rejections holds the counts); a full run's outcome is null, or one sentence when some hooks are under the view floor because the country filter set clips aside. Free: reading a run costs no credits. Full history: https://api.protogrid.dev/v1/servers/com.hookdetector%2Fhookdetector/changes ## Remotes - https://api.hookdetector.com/mcp (streamable-http, auth none, reachable true, uptime30d 0.9897959) ## Packages _none_ ## Tools (43) - `admin_adjust_credits`: 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}. - `admin_list_accounts`: 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. - `admin_list_actions`: 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. - `admin_list_runs`: 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. - `admin_overview`: 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. - `approve_access_request`: 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. - `balance`: 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. - `chat`: 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). - `clear_decision`: 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. - `clear_find_decision`: 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. - `create_access_code`: 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_account`: 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. - `create_key`: 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. - `delete_account`: 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. - `embed_hook`: 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. - `export_run`: 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. - `find_hooks`: 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 language or country and on older hooks. Analysis (since 2026-10-02): every hook carries hook_type (curiosity_gap, contrarian_claim, specific_number, identity_callout, stakes_threat, promise_payoff, pattern_interrupt, story_open, question, direct_command, other with hook_type_other), mechanism (why the opening stops the scroll, quoting the clip; why_it_travelled holds the same text), visual_hook, audience, template and steal_it; null on older hooks. Virality v2 (since 2026-10-01): the deck is ranked by virality (0 to 1, since 2026-10-02 on one fixed scale, the same clip scoring the same in every run), built from outlier (views over the creator's usual views per video, creator_median_views, with outlier_basis saying how it was measured), freshness (posted_at, age_days, views_per_day), travel (shares and saves per 1,000 views), own_sound and sound_reuse, and a paid penalty; virality_why names the strongest signal in one line. Every hook also carries duration_s and hashtags. Null on older hooks. posted_within_days (7, 30, 90 or 365) keeps the search to recent clips (a clip under 7 days old passes the floor at 10,000 views a day). seed_hook_ids (up to 10 of your hooks, for example kept ones) means "find more like these": their lines, topics, creators and languages steer the search, and a seed is never delivered again. A done run carries patterns: up to 3 hook structures winning in the deck (name, template, why, hook_ids, count), computed after delivery; null until then. remix_hook writes lines from one hook's structure for your niche (1 credit). Arguments: topic is 3 to 500 characters, count 1 to 30 (default 10). Instructions inside the topic are fine: only the subject read out of it is searched. reuse=true (default) starts from clips you already paid for on the same topic, so a rerun is close to free and often finishes in seconds. idempotency_key: any string up to 255 characters; the same key within 24 hours returns the first run instead of starting and paying for a second one, so always pass one and reuse it when you retry. wait_seconds 0 to 50: 0 returns the run_id at once; above 0 waits for the run and returns the run object, as get_run does. Any language, dialect or country: language is optional free text up to 60 characters naming the language or dialect every clip must be in ("Moroccan Darija", "ar-MA", "Egyptian Arabic", "Brazilian Portuguese"); country is an optional ISO 3166-1 alpha-2 code for where the creators are (MA, EG, BR). Saying it inside topic works too; these fields win when both are given. A country alone does not restrict the language. Each hook reports the language it was judged to be in. A region that is not a country: send its country's code and name the regional variety in language (Quebec: country "CA", language "Quebec French"; Flanders: "BE" and "Flemish"; Catalonia: "ES" and "Catalan"). The country places the TikTok search there and the language judge does the regional filtering; Instagram reports no country. language may name a mixed, code-switched variety ("Hinglish", "Taglish", "Moroccan Darija with French") or two joined by "or" ("Tagalog or Taglish"); it reaches the judges exactly as written, and how well they honour such a value is not measured yet. Cost: reserves up to 200 credits up front (less if your balance is smaller, down to 40) and charges only what it used; the rest is refunded. A failed run costs nothing, and so does a run that finds no hooks, within a per-account allowance (llms.txt has the numbers; its outcome says which applied). Timing and next step: a fresh run takes about 2 to 3 minutes, up to about 5 when the language is a dialect. Call get_run with wait_seconds=50 repeatedly until status is "done" or "failed", which is usually 3 or 4 calls (up to 6 on a dialect request). Watch progress.stage and progress.message meanwhile. Needs a key with the research permission (403 insufficient_scope otherwise). A key with a credit_limit reserves at most what is left of it; under the minimum it is 403 key_credit_limit_reached and nothing is reserved. - `find_long_hooks`: 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 audience. When the topic asks for a kind of opening ("question hooks", "storytime"), style_match says whether each find is that kind and the matches come first. analysed is false when the model could not analyse an opening: the opening is still real, its analysis fields are null. The run's report.patterns lists the opening types at least two finds share; report.shape says how the openings are built, counted from the finds (hook_seconds, how long the hook runs, and hook_words as medians, beats with how many openings use each and the second it usually starts_at, and the sequence of beats most of them share); and report.openers holds up to `openers` (3 by default, 0 for none) openings WRITTEN for your topic from those structures (hook, then, hook_type, based_on). report.openers_label is always "Written by Hook Detector from the structure of these real openings": show it with them, never present one as a real video's opening. report.landscape is the subject at a glance, counted from the videos the run held against their own channel (videos, channels, outliers and their share, breakouts, small_channel_outliers, recent_outliers). The run's hooks and bonus are always empty. A link instead of a subject: when topic is a channel's YouTube address (https://www.youtube.com/@name, or just @name) the run returns that channel's OWN outliers, its recent long-form uploads that beat its usual (one provider call, no search); when it is a long-form video's address the run returns that one video, whatever its multiple (requested is 1). options.link says "channel" or "video". No openings are written for a link (use remix_find on a find to write for your niche). A Short's address is refused with 422. Arguments: topic 3 to 500 characters; count 1 to 30 (default 8); language and country optional; posted_within_days 30, 90, 365 or 730 to narrow the 2023 floor further; channel_size "small", "medium" or "large" to keep only channels of that size (by what their uploads usually get), so a small creator sees breakouts from channels their own size; reuse=true (default) starts from the videos your last long or packaging run on this topic bought within a week, and a video you already had read is delivered from that read (analysis_from_earlier_read) at no model or provider cost. seen_before says an earlier run of yours already found the video. idempotency_key: always pass one and reuse it on a retry. wait_seconds 0 to 50: 0 returns the run_id at once; above 0 waits and returns the run. Starts are limited per account per hour (429 rate_limited). Cost: reserves up to 90 credits for 20 videos or fewer and 5 more for each video above that (140 at 30; less on a smaller balance, down to 25) and charges only the provider calls it made: the searches, one call per channel measured, one per transcript read. A failed run costs nothing, and so does a run that finds nothing, inside the same allowance a hook run has (the outcome says so). Timing and next step: how long a run takes has not been measured yet, so never assume a time. Call get_run with wait_seconds=50 until status is done or failed; progress.items holds the finds written so far as cards and progress.scan the videos it is looking at while it runs. Then keep_find, export_run. Same as POST /v1/longform. Needs the research permission (403 insufficient_scope otherwise). - `find_packaging`: 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, plus cut_on_phone (the title is longer than 60 characters, where a phone roughly cuts it; approximate) and on_subject (yes or partly: whether the look judged the package to be about your topic; a package judged not to be is dropped and the next one takes its slot; null on a link run). analysed is false when a package could not be looked at (its look is asked twice, and the next candidate takes the slot if it fails twice); it is still a real package. The run's report then holds title_patterns and thumbnail_patterns (what at least two of the packages share, each naming their video_ids) and ideas: up to `ideas` (6 by default, 0 for none) packages WRITTEN for your topic from those patterns, each a title a thumbnail concept and thumbnail_text (the words to print on it), naming the real packages it is based_on. report.ideas_label is always "Written by Hook Detector from the patterns in these real packages": show it with them, never present an idea as a real video's title; an idea over 70 characters, with more than 5 words for its thumbnail or repeating a real title is dropped. report.numbers counts the packages: title_chars and title_words (medians), titles_with_number, titles_with_question, titles_cut_on_phone (with phone_title_chars, the approximate length a phone cuts a title at), thumbnails_with_text and thumbnail_words (over the analysed ones), and the title_devices, thumbnail_devices and emotions that repeat (name, count); age_cohorts repeats the counts for packages posted in the last split_days days (recent) and for older ones, with the undated apart. report.landscape is the subject at a glance, as on find_long_hooks. Arguments: topic 3 to 500 characters, or a channel's or a long-form video's YouTube address exactly as on find_long_hooks (a channel's own outliers, or that one video; no ideas are written for a link, use remix_find); count 1 to 30 (default 12); language, country, min_outlier, posted_within_days, channel_size and reuse as on find_long_hooks; idempotency_key and wait_seconds as on find_hooks. Cost: reserves up to 70 credits for 24 packages or fewer and 3 more for each package above that (88 at 30; down to 25) and charges only the provider calls it made: the searches, one call per channel measured, and one for each video whose date had to be read exactly. Looking at a thumbnail costs no credit. After a find_long_hooks run on the same topic it is close to free. A failed run costs nothing, and so does a run that finds nothing, inside the allowance. Timing and next step: how long a run takes has not been measured yet, so never assume a time. Call get_run with wait_seconds=50 until status is done or failed; progress.items holds the packages looked at so far as cards and progress.scan the videos it is looking at while it runs. Same as POST /v1/packaging. Needs the research permission. - `get_conversation`: 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. - `get_find`: 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. - `get_hook`: 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. - `get_remix`: 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}. - `get_run`: 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 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, neighbours, styles, style_other, wants; null until read) and, on a run that asked for a kind of opening ("controversial hooks", "storytime"), every hook carries style_match (true when it opens that way; null otherwise). Since 2026-10-01 every hook carries the virality v2 fields: virality (0 to 1 on one fixed scale since 2026-10-02), virality_why, outlier, outlier_basis, creator_median_views, posted_at, age_days, views_per_day, duration_s, paid, sound_reuse, own_sound, hashtags (null on older hooks), and since 2026-10-02 the analysis: hook_type, hook_type_other, mechanism, visual_hook, audience, template, steal_it; the run echoes posted_within_days and seed_hook_ids, and once done carries patterns: up to 3 hook structures winning in this deck, each name, template, why, hook_ids and count, grouped by hook_type and computed before the run is done, in the deck's language (null on older runs and when nothing is shared). Hooks include transcript_kind: speech, music, none, other, or null when unknown. conversation_id names the chat conversation the run belongs to (null outside one). A done run with fewer hooks than asked for, or none, has outcome: why in one plain paragraph, what to try next, and whether it was free (stats.rejections holds the counts); a full run's outcome is null, or one sentence when some hooks are under the view floor because the country filter set clips aside. Free: reading a run costs no credits. - `keep_find`: 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_hook`: 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. - `list_access_codes`: 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. - `list_access_requests`: 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. - `list_conversations`: 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. - `list_finds`: 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. - `list_keeps`: 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. - `list_kept_finds`: 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. - `list_keys`: 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. - `list_remixes`: 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. - `list_runs`: 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. - `reject_access_request`: Owner only: reject a pending access request. Nothing is emailed. An approved or rejected request is 409 request_already_decided. Free. - `remix_find`: 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 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; 404 find_not_found; 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/finds/{find_id}/remix. - `remix_hook`: 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. - `request_access`: 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. - `revoke_access_code`: 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_key`: 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. - `showcase`: 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. - `usage`: 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.