Hook Detector

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 inva…

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_u…

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 ba…

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; thu…

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

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

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

One 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}.

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, …

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

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

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

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

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

The index: every video your long and packaging runs found, across all runs, one entry a video on each tab (its newest read, with the keep or reject made on the video). Each is a full find object: the title and thumbnail_url as YouTube shows them, views, channel_median_views, outlier (views over the channel's usual) and outlier_score (0 to 100 on one fixed scale, so entries from different runs rank together), plus the analysis its run wrote. q (at most 120 characters) looks in the title, the channel, the hook as it was said, and what the thumbnail prints and shows, s…

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

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

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

The 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.

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.

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

Make it mine, for a long-form opening or a package: write up to n (1 to 5, default 3) new ones for your niche that keep one real find's structure. From a long find, `written` holds openings: hook (what the creator says first), then (what the next half minute has to deliver) and kept_structure, built on the find's template and its order of beats. From a packaging find it holds packages: title, thumbnail (what to show and how to frame it), thumbnail_text (the words to print, or null) and kept_structure, built on its title template and its thumbnail's composition. Wri…

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…

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.

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

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

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.

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.