# Hook Detector

Find short-form hooks that already work. Give a topic, get back real TikTok, Instagram and
YouTube Shorts clips with their opening lines, why each one travelled and how viral it
really was (an outlier against its creator's usual, fresh views per day).

Three kinds of research, one run object, the same wait:

    short form    POST /v1/research    hooks from TikTok, Instagram and YouTube Shorts
    long form     POST /v1/longform    how the long-form YouTube videos that beat their
                                       own channel open (the first minute, verbatim)
    packaging     POST /v1/packaging   those videos' titles and thumbnails, what they
                                       share, and written ideas for your topic

Base URL: https://api.hookdetector.com
MCP: https://api.hookdetector.com/mcp (streamable HTTP; /mcp and /mcp/ both work)
OpenAPI: https://api.hookdetector.com/openapi.json
MCP registry entry: https://api.hookdetector.com/server.json and https://api.hookdetector.com/.well-known/mcp.json
The full manual as one Markdown file to download: https://api.hookdetector.com/docs.md
A person to write to: contact@hookdetector.com (questions, data removal without your key, security reports)

Hook Detector is in beta: a new account needs an access code (see "Get in" below). Keys made
before the beta keep working.

The shortest path for an agent: POST /v1/accounts with your access_code, then POST
/v1/research with an Idempotency-Key, then GET /v1/runs/{run_id}?wait=55 until status is done (3 or 4
calls). Set your HTTP client's read timeout above the wait, for example 55 + 15
seconds, or the client gives up before the server answers.

## Every route

    POST /v1/accounts                        sign up with a beta access code, no auth
    GET /v1/me                               your account and balance
    DELETE /v1/account                       erase your account and all its data
    GET /v1/usage                            credits, spend, holds, last 30 days
    GET /v1/keys                             your active API keys
    POST /v1/keys                            create another API key
    DELETE /v1/keys/{key_id}                 revoke a key ("others": every key but yours)
    POST /v1/research                        start a run (Idempotency-Key honoured)
    GET /v1/runs/{run_id}?wait=N             one run and its hooks or finds, waiting up to N s
    GET /v1/runs/{run_id}/export?format=csv  a run's results as a file: csv, json or md
    GET /v1/runs?kind=                       your runs of every kind, newest first (paged)
    POST /v1/longform                        long form: how YouTube outliers on a topic open
    POST /v1/packaging                       packaging: their titles and thumbnails, and ideas
    GET /v1/finds?kind=packaging&sort=score  the index: every video your runs found, one entry a video on each tab, by outlier score (paged)
    GET /v1/finds/keeps?kind=long            the long-form hooks and packages you kept (paged)
    GET /v1/finds/{find_id}                  one find (a long or packaging result)
    POST /v1/finds/{find_id}/decision        keep or reject a find
    DELETE /v1/finds/{find_id}/decision      clear a keep or reject on a find
    POST /v1/finds/{find_id}/remix           make it mine: openings or packages written from this find's structure, or (mode intro, video_brief) Write my intro: your own timed intro in a long find's structure, 1 credit
    GET /v1/finds/{find_id}/remixes          the remixes you paid for from this find, newest first
    GET /v1/remixes/{remix_id}               one remix you paid for
    GET /v1/hooks/{hook_id}                  one hook
    GET /v1/hooks/{hook_id}/embed            playable embed
    GET /v1/hooks/{hook_id}/still            the card image as a JPEG, no key needed
    GET /v1/hooks/{hook_id}/media            The clip's original video file, for a <video> tag
    GET /v1/runs/{run_id}/thumbs/{key}       a live wall clip's cover as a JPEG, no key needed
    GET /v1/showcase?n=12                    real delivered talking-head hooks for a wait screen, no key
    POST /v1/hooks/{hook_id}/decision        keep or reject
    DELETE /v1/hooks/{hook_id}/decision      clear a keep or reject (undo)
    POST /v1/hooks/{hook_id}/remix           make it mine: written lines from this hook's structure, 1 credit (Idempotency-Key honoured)
    GET /v1/hooks/{hook_id}/remixes          the remixes you paid for from this hook, newest first
    GET /v1/keeps                            the hooks you kept (paged)
    GET /v1/folders?kind=packaging           your folders on every tab, each with its count, cover and share link
    POST /v1/folders                         make a folder on one tab (the same name again is that folder)
    GET /v1/folders/{folder_id}              one folder and its items with their notes (paged)
    PATCH /v1/folders/{folder_id}            rename a folder or change its description
    DELETE /v1/folders/{folder_id}           delete a folder, its items and its share link
    POST /v1/folders/{folder_id}/items       file a hook or a find, with an optional note
    PATCH /v1/folders/{folder_id}/items/{item_id}  edit an item's note
    DELETE /v1/folders/{folder_id}/items/{item_id}  take an item out of a folder
    POST /v1/folders/{folder_id}/share       turn on a folder's public read-only link
    DELETE /v1/folders/{folder_id}/share     turn the link off at once
    GET /v1/shared/folders/{token}           a shared folder as its link shows it, no key
    GET /v1/swipe                            the swipe file: title structures of your kept or filed packages
    POST /v1/chat                            one chat turn
    GET /v1/conversations                    your conversations (paged)
    GET /v1/conversations/{conversation_id}?limit=100&before=  one conversation, newest messages first (paged)
    GET /v1/shorts/trending?subject=&platform=&window=7d  the short videos rising now on a subject: plays per hour and the multiple over the creator's usual, free
    POST /v1/review/short                    rate one public Reel, TikTok or Short against the real finds on its subject, 3 credits (Idempotency-Key honoured)
    GET /health                              liveness: process, database, commit, runs_in_flight
    GET /health/deep                         readiness, migrations, provider status, commit
    GET /.well-known/mcp.json                the same entry, at the well-known path
    GET /server.json                         the MCP registry entry
    GET /llms.txt                            this guide
    GET /hookdetector-docs.md                the same manual
    GET /docs.md                             the full manual, a Markdown download
    POST /v1/presets                         save a named set of filters for a tab
    GET /v1/presets                          your saved filter presets
    DELETE /v1/presets/{preset_id}           delete a saved preset
    POST /v1/titles                          titles, each from a real outlier (1 credit)
    GET /v1/calls/{call_id}                  a paid tool's call read back
    GET /v1/calls                            your paid tools' calls, newest first
    POST /v1/ideas                           video ideas built on real outliers (1 credit)
    GET /v1/finds/{find_id}/similar          videos, titles or thumbnails like one of your finds
    GET /v1/index/thumbnails                 thumbnails by what the picture shows
    POST /v1/index/thumbnails/by-image       thumbnails like a picture you send
    POST /v1/packaging/score                 score my package against the outliers (1 credit)
    POST /v1/packaging/preview               my package in a mock feed, as a PNG
    POST /v1/thumbnails                      make thumbnails, every printed word checked (4 a 1K image)
    GET /v1/thumbnails/{call_id}             a thumbnails call: concepts and images
    POST /v1/thumbnails/edit                 edit a thumbnail: erase, change a part, swap a face, text, upscale
    POST /v1/thumbnails/recreate             recreate any YouTube video's thumbnail as yours
    POST /v1/optimize                        new packages for a published video, each scored (10 a package)
    GET /v1/optimize/{call_id}               an Optimize call: original and packages
    POST /v1/ab                              pack 2 or 3 thumbnails for YouTube's Test and Compare
    POST /v1/access/requests                 ask for an access code, no auth
    GET /v1/admin/requests                   admin: access requests
    POST /v1/admin/requests/{request_id}/approve  admin: approve; the code is emailed and returned once
    POST /v1/admin/requests/{request_id}/reject  admin: reject
    GET /v1/admin/codes                      admin: list codes (never the code itself)
    POST /v1/admin/codes                     admin: make a code (shown once)
    DELETE /v1/admin/codes/{code_id}         admin: revoke a code
    GET /v1/auth/google/start                people: sign in with Google (a browser redirect)
    GET /v1/auth/google/callback             where Google sends the browser back
    POST /v1/auth/exchange                   the web trades a one-time token for a key
    POST /v1/auth/signout                    revoke the key making the call
    POST /v1/auth/admin-signin               the owner signs in with the admin password
    GET /v1/admin/overview                   admin: the whole service at a glance
    GET /v1/admin/accounts?q=                admin: every account, searchable (paged)
    POST /v1/admin/accounts/{account_id}/credits  admin: add or remove credits, audited
    GET /v1/admin/runs                       admin: every account's runs
    GET /v1/admin/actions                    admin: the audit of admin actions
    POST /v1/runs/{run_id}/share             share a finished Short form run as a public page; returns its url (same url every time)
    GET /v1/shared/{token}                   a shared run's public page as JSON: topic and public hook fields, no key
    POST /v1/jobs                            Start a background job (echo)
    GET /v1/jobs                             This account's background jobs, newest first
    GET /v1/jobs/{job_id}                    One background job
    GET /v1/index/search                     Search the shared index of YouTube outliers, free
    GET /v1/index/random                     Outliers at random from the shared index, free
    GET /v1/channels/search                  Find channels by name or handle, free
    GET /v1/channels/{ref}                   A channel page: every recent upload scored, outliers, momentum
    GET /v1/channels/{ref}/outliers          A channel's outliers, or outliers for a channel like it
    GET /v1/channels/{ref}/similar           Channels like this one
    GET /v1/niches                           The niche explorer: every niche reported, with its numbers
    GET /v1/niches/{slug}                    A niche report counted from the shared index
    GET /v1/videos/{video_id}/stats          A video's views per hour and its history
    GET /v1/winners                          Real title and thumbnail changes, with views per hour before and after
    GET /v1/winners/{change_id}/thumb/{side}  A changed thumbnail, old or new, as a JPEG for an <img> tag
    POST /v1/trackers                        Make a tracker: a folder of channels with a feed and alerts
    GET /v1/trackers                         Your trackers, or the public ones
    GET /v1/trackers/alerts                  Your tracker alerts, newest first
    GET /v1/trackers/{tracker_id}            One tracker
    PATCH /v1/trackers/{tracker_id}          Change a tracker's name, sharing or alert lines
    DELETE /v1/trackers/{tracker_id}         Delete a tracker
    POST /v1/trackers/{tracker_id}/channels  Add channels to a tracker
    DELETE /v1/trackers/{tracker_id}/channels/{ref}  Take a channel off a tracker
    GET /v1/trackers/{tracker_id}/feed       A tracker's feed: its channels' uploads by multiple
    POST /v1/trackers/{tracker_id}/clone     Clone a public or shared tracker
    POST /v1/alerts                          Save a search and get alerts on new outliers
    GET /v1/alerts                           Your saved searches and their newest hits
    GET /v1/alerts/{alert_id}                One saved search and its hits
    PATCH /v1/alerts/{alert_id}              Change a saved search
    DELETE /v1/alerts/{alert_id}             Delete a saved search
    POST /v1/alerts/{alert_id}/run           Check a saved search now
    POST /v1/webhooks                        Get tracker alerts and search hits posted to your URL, signed
    GET /v1/webhooks                         Your webhooks
    DELETE /v1/webhooks/{webhook_id}         Delete a webhook
    POST /v1/webhooks/{webhook_id}/test      Send a signed test delivery now
    GET /v1/webhooks/{webhook_id}/deliveries  A webhook's deliveries, newest first
    GET /v1/videos/{video_id}/scorecard      Everything we know about one video, free
    GET /v1/trends                           Rising topics: words and phrases more videos are using
    GET /v1/formats                          Title formats that win: skeletons with their multiples and adoption
    GET /v1/formats/{format_id}              One title format's videos, strongest first
    GET /v1/ideas/daily                      Your daily ideas, newest day first
    POST /v1/agents                          An agent that reviews each new upload of a tracker's channels
    GET /v1/agents                           Your agents and what they spent this month
    GET /v1/agents/{agent_id}                One agent and its reviews
    PATCH /v1/agents/{agent_id}              Change an agent's budget, name or pause it
    DELETE /v1/agents/{agent_id}             Delete an agent
    POST /v1/finds/{find_id}/skeleton        a long-form find's whole video mapped, every quote checked (5 credits)
    GET /v1/finds/{find_id}/skeleton         that skeleton read back, free
    POST /v1/review                          Video Review of your own YouTube video (15 credits)
    POST /v1/review/graph                    your YouTube Studio retention graph read (1 credit)
    POST /v1/review/hook                     Hook Review of your opening (3 credits)
    POST /v1/openings                        openings for your video, each from a real outlier (1 credit)
    POST /v1/scripts                         a full script built from real outlier skeletons (10 credits)
    POST /v1/scripts/review                  Script Review of your script (3 credits)
    POST /v1/review/edit                     Edit Review of your cut, with markers to download (25 credits)
    POST /v1/review/edit/upload              Edit Review of your cut sent as the file itself, the request body, up to 500 MB, with ?filename= (25 credits)
    POST /v1/seo                             an upload pack: description, chapters, tags (1 credit)
    POST /v1/clean/files                     stage a recording for the cleaner: the file itself as the body, up to 500 MB, with ?filename= (free)
    POST /v1/clean                           the talking-head cleaner: silences, retakes, fillers cut with reasons, other mics synced; Premiere XML, FCPXML, EDL (15 credits)
    GET /v1/strategies?q=                    the hook strategy library: each kind of long-form hook, counted from the index (free)
    POST /v1/keywords                        keyword research: estimated volume, competition, a 0 to 100 score with its five bands, related terms, questions, rising terms (2 credits)
    GET /v1/team                             your team: seats, the shared pool, members; the owner also sees usage and open invites
    POST /v1/team                            create a team you own, its pool funded from your balance
    POST /v1/team/credits                    move credits between your balance and the team's pool (owner)
    POST /v1/team/invites                    a single-use invite link, emailed to the person, valid 7 days (owner)
    DELETE /v1/team/invites/{invite_id}      revoke an open invite (owner)
    GET /v1/team/invites/{token}             what an invite link joins, before accepting
    POST /v1/team/invites/{token}/accept     join the team: its pool pays your spending, your runs stay private
    DELETE /v1/team/members/{member_id}      remove a member, or me to leave
    PATCH /v1/team/members/{member_id}       a member's monthly cap on the pool (owner)
    POST /v1/comments/insights               questions and pain points in the comments of a subject's outliers, each counted in code with 2 real comments (3 credits)
    POST /v1/sponsors                        who sponsors the channels on a subject: brands, codes and links from the outliers' descriptions (1 credit)
    POST /v1/free/title                      free, no key: score a title against real outliers (5 a day)
    GET /v1/free/outlier?url=                free, no key: a video's multiple, band and views per hour (5 a day)
    GET /v1/free/preview?subject=            free, no key: real outliers for a feed preview (5 a day)
    GET /v1/free/thumbnail?url=              free, no key: a video's thumbnail URLs on i.ytimg.com (5 a day)
    POST /v1/free/hooks                      free, no key: 5 short-form hook lines from real hooks (5 a day)
    GET /v1/public/{kind}                    the listed public pages of a kind (niches, creators, teardowns), no key
    GET /v1/public/{kind}/{slug}             one public page's data, every number from a real index row, no key
    POST /v1/thumbnails/attention            a predicted attention heatmap on a thumbnail (UNISAL), free
    POST /v1/polls                           put 2 to 4 packages to Hook Detector's users, who pick the one they would click, 2 credits
    GET /v1/polls                            your polls with their results
    GET /v1/polls/next                       a poll waiting for your vote, options in your own order, no counts
    GET /v1/polls/{poll_id}                  one poll: votes, shares, 95% intervals, leader, slots, reasons
    DELETE /v1/polls/{poll_id}               delete a poll, its votes and pictures
    POST /v1/polls/{poll_id}/vote            vote with the slot you picked and an optional reason
    POST /v1/polls/{poll_id}/close           end your poll now, its votes kept
    GET /v1/videos/badges?ids=               badges for up to 50 videos: views, the multiple and views per hour, free
    GET /v1/findings                         the research findings counted from the index, each run twice on samples of different channels, no key
    GET /v1/findings/{slug}                  one research page: both runs' numbers per claim, n per run, reproduced or not, no key

OpenAPI 3.1 with typed responses and examples: https://api.hookdetector.com/openapi.json (browsable at https://api.hookdetector.com/docs).

## Get in: the beta access code

A new account needs a beta access code, on every door (REST, MCP and the website). One
code works anywhere. It looks like HD-XXXX-XXXX; case and dashes do not matter.

- Ask for one: open https://hookdetector.com/access, or send
  POST https://api.hookdetector.com/v1/access/requests with {"email": "you@example.com", "note": "<optional>"}
  (no key; 202 {"status": "pending" or "emailed", "message"}; MCP request_access;
  5 per address per hour). The
  owner approves the request and the code arrives by email from access@hookdetector.com.
- Or get one from the owner directly: contact@hookdetector.com.
- A code may be single use and may expire. Keys made before the beta keep working and need
  no code.

An agent without a code cannot make one: ask the person you work for to request it, then
pass it as below.

## Start from nothing

    curl -X POST https://api.hookdetector.com/v1/accounts -H "content-type: application/json"       -d '{"access_code": "HD-XXXX-XXXX"}'

Optional in the same body: "label" (your note, up to 120 characters). Returns an
api_key and free credits. The key is shown once. Send it on every other call as:
Authorization: Bearer hd_...

With no code it is 403 access_code_required; with a wrong, used up, expired or revoked code
it is 403 invalid_access_code. Both details point to
https://hookdetector.com/access. Failed codes are limited to 10 per address per hour, so
a code cannot be guessed. While the server cannot check codes (it is not configured for
them) a signup is 503 access_unavailable and nothing is created: it fails closed, never
open.

    curl https://api.hookdetector.com/v1/me -H "authorization: Bearer $KEY"

returns your account_id, credits, key_prefix and key_id (of the key you called with),
label and created_at.

To erase the account and everything in it (every key, run, hook, decision, conversation
and message; unspent credits go with it; it cannot be undone):

    curl -X DELETE https://api.hookdetector.com/v1/account -H "authorization: Bearer $KEY"       -H "content-type: application/json" -d '{"confirm": "delete my account"}'

returns {"deleted": true, "account_id", "erased": {counts per kind}, "message"}. Any
other body is 422 confirmation_required, and while a run is queued or running it is 409
run_in_flight. Every key of the account stops working at once.

## API keys

An account can hold up to 10 active keys, for example one per agent or
machine, so one can be revoked without touching the others. Every active key reaches the
same account, credits and runs. Keep a key in an environment variable or a secrets
manager, never in client-side code, a public repository or a shared document.

Each key holds some of four scopes (permissions):

    read      read the account, usage, runs, hooks, finds, embeds, keeps, conversations and exports
    write     keep, reject or undo a hook or a find, file them in folders and share a folder, and send chat turns
    research  start research runs (POST /v1/research, find_hooks, or a chat turn that starts one; POST /v1/longform and /v1/packaging, find_long_hooks and find_packaging), and rate a short (POST /v1/review/short, review_short), which spend credits
    admin     list, create and revoke keys, and delete the account: full control

A call the key lacks the scope for is 403 insufficient_scope, and the detail names the
scope. The signup key, and every key made before scopes existed, hold all four. A key
created without "scopes" holds all four too; give an agent only what it needs.

    curl https://api.hookdetector.com/v1/keys -H "authorization: Bearer $KEY"

returns {"keys": [{"key_id", "name", "prefix", "created_at", "last_used_at",
"current"}], "scopes": [the calling key's], "access": {"<key_id>": {"scopes",
"credit_limit", "credits_used", "expires_at", "expired"}}}. The signup key is key_id
"original", name "Original key". current is true for the key making the call.
last_used_at is updated at most every 5 minutes. credits_used is what runs started with
the key spent (a run in flight counts what it holds). A key itself is never shown again
after it is created. Needs admin; GET /v1/me shows any key its own scopes.

    curl -X POST https://api.hookdetector.com/v1/keys -H "authorization: Bearer $KEY"       -H "content-type: application/json"       -d '{"name": "agent", "scopes": ["read", "write", "research"], "credit_limit": 1000, "expires_in_days": 90}'

returns 201 {"key_id", "name", "prefix", "api_key", "created_at"}. api_key is shown this
once: store it. Every field is optional: name up to 60 characters; scopes a
non-empty list (all four when left out); credit_limit 1 to 100000, the most
credits runs started with this key may spend over its life (a run then reserves at most
what is left of it, and under the minimum a run needs it is 403
key_credit_limit_reached, nothing reserved); expires_in_days 1 to 365,
after which the key is refused with 401 key_expired. Needs admin. 409 at
10 active keys (an expired key holds no slot); key creation is rate
limited per account per hour (429).

    curl -X DELETE https://api.hookdetector.com/v1/keys/$KEY_ID -H "authorization: Bearer $KEY"

revokes a key at once; key_id may be "original". Any key may revoke itself (the response
says so in current and message); revoking another needs admin. Revoking the last usable
key is refused with 409: create another first. An unknown or already revoked key is 404.

If a key leaked, revoke every key but the one you are calling with:

    curl -X DELETE https://api.hookdetector.com/v1/keys/others -H "authorization: Bearer $KEY"

returns {"key_id": "others", "revoked": true, "revoked_count", "revoked_at", "current":
false, "kept": "<your key_id>", "message"}. Needs admin. The calling key always survives.

## Usage

    curl https://api.hookdetector.com/v1/usage -H "authorization: Bearer $KEY"

returns credits (balance now), spent_total (charged by finished runs), reserved_now
(credits held by runs still in flight), runs_total, last_30_days (30 entries, one per UTC
day, oldest first: date, runs, charged) and recent (your 20 newest runs: run_id, kind,
topic, status, reserved, charged, created_at, finished_at). credits + spent_total + reserved_now
is everything the account was given. spent_total and each day's charged include "make it
mine" remixes (one credit each, on the UTC day they were asked), so the 30 days add up to
spent_total within the window; a remix still being written is in reserved_now; recent
lists runs only.

## Find hooks

    curl -X POST https://api.hookdetector.com/v1/research \
      -H "authorization: Bearer $KEY" -H "content-type: application/json" \
      -d '{"topic":"short term rental tax strategy","count":10}'

Body:

    topic            required, 3 to 500 characters. Instructions inside
                     it are fine: a long topic is searched by the subject read out of
                     it, never verbatim
    count            optional, 1 to 30, default 10
    reuse            optional, default true: start from rows you already paid for on the
                     same topic, so a second cut is close to free
    conversation_id  optional, one of your conversations (from /v1/chat) to attach the run to
    language         optional, up to 60 characters: the language or dialect every
                     clip must be in, in words or as a tag ("Moroccan Darija", "ar-MA",
                     "Egyptian Arabic", "Brazilian Portuguese"). Any language works,
                     including a regional variety ("Quebec French") or a mixed,
                     code-switched one ("Hinglish", "Taglish", "Moroccan Darija with
                     French"), or two joined by "or" ("Tagalog or Taglish"). The judges
                     get it exactly as written; see mixed varieties below.
    country          optional, assigned ISO 3166-1 alpha-2 code for where the creators are
                     (MA, EG, BR; UK is read as GB); upper-cased for you, anything else is
                     422 invalid_request. A country alone does not restrict the language.
                     Not a region code: see regions below. The schema advertises two
                     letters; surrounding spaces are also accepted, and "" is the same as
                     leaving it out.
    posted_within_days  optional, since 2026-10-01: how recent the clips must be, 7, 30, 90
                     or 365 (days); null or left out is any time. The search asks the
                     platforms for that window, and a clip under 7 days old passes the
                     view floor at 10,000 views a day. Anything else is 422.
    seed_hook_ids    optional, since 2026-10-01: up to 10 ids of your own hooks (kept
                     ones from /v1/keeps, or any you can read): "find more like these".
                     Their lines, topics, creators and languages steer the search phrases
                     and the creators expanded; a seed is never delivered again. A hook
                     that is not yours is 422 invalid_request.
    platforms        optional, since 2026-10-10: which platforms to search and deliver
                     from, a non-empty list of "tiktok", "instagram" and "youtube" (YouTube
                     Shorts). Left out, or all three, searches all three; ["instagram"]
                     delivers Instagram reels only. Case does not matter and a repeat counts
                     once; an empty list or any other name is 422 invalid_request naming
                     platforms. The run echoes it as `platforms` (all three when none was
                     asked). The chat body takes it too, for the run its turn starts.

Any language, dialect or country. Darija from Moroccan creators:

    curl -X POST https://api.hookdetector.com/v1/research \
      -H "authorization: Bearer $KEY" -H "content-type: application/json" \
      -d '{"topic":"building a startup","count":10,"language":"Moroccan Darija","country":"MA"}'

Brazilian Portuguese from Brazil is {"language":"Brazilian Portuguese","country":"BR"}.

A region that is not a country: send its country's code and name the regional variety in
language. Quebec is {"country":"CA","language":"Quebec French"}, Flanders
{"country":"BE","language":"Flemish"}, Catalonia {"country":"ES","language":"Catalan"}.
The country places the TikTok search in that country; the language judge does the
regional filtering, keeping only clips in that variety. Instagram reports no country, so
there the language check alone applies. A region code is refused with 422: one in the
ISO 3166-2 shape ("CA-QC", "US-TX") is answered with its country, a bare one ("QC") with
this rule. A two-letter code that is both a US state and a country (MA, CA, IN, GA, DE,
CO) is always read as the country: MA is Morocco, never Massachusetts.

A mixed variety ("Hinglish", "Moroccan Darija with French") or two values joined by "or"
("Tagalog or Taglish") is accepted as one language value and handed to the judges exactly
as written, as the variety every clip must be in. How well the judges honour a mixed or
either-of value is not measured yet; a single named variety is the measured path.
Saying it inside the topic works too ("hooks about building a startup, only in darija from
moroccans"): a first step splits the request into the subject and the locale. A topic
that is only about a place ("Dubai real estate") is not narrowed to that country's
creators. The explicit fields win when both are given and are used exactly as you wrote
them. TikTok searches are placed in that country, clips
TikTok places in another country are dropped before any credit is spent, search phrases
are written the way locals type them, and the judges reject other languages and
neighbouring dialects on what the clip says and shows; a clip whose language cannot be
checked is not delivered. Instagram rows carry no country, so
on Instagram only the language check applies. reuse only starts from a run with the same
topic, language and country. The Idempotency-Key fingerprint includes language and country
when set.

Returns 202 with a run_id and credits_reserved straight away. A fresh run takes about 2
to 3 minutes (up to about 5 when the language asked for is a dialect); a rerun of a topic you already paid for is often seconds.

Retry safely with an Idempotency-Key header (any visible ASCII, 1 to
255 characters). The same key on the same account within
24 hours returns the first run with 200, the same body and the header
Idempotent-Replayed: true, and reserves nothing. The same key with a different body is
422. A request refused before a run was created (402, 422) stores nothing, so retry it
with the same key.

    curl -X POST https://api.hookdetector.com/v1/research -H "authorization: Bearer $KEY"       -H "content-type: application/json" -H "Idempotency-Key: $(uuidgen)"       -d '{"topic":"cold plunge recovery","count":10}'

Then wait for it. ?wait=N (0 to 55) holds the request until the run is done or
failed, or N seconds pass, and returns the run either way. Loop while status is queued or
running:

    curl "https://api.hookdetector.com/v1/runs/$RUN_ID?wait=55" -H "authorization: Bearer $KEY"

An account may have 2 runs queued or running at once. A start beyond that is
429 with code too_many_runs and a Retry-After, and reserves nothing: wait for a run to
finish, then start the next. All research across the service is also capped per UTC day;
when today's capacity is used up a start is 503 with code at_capacity and a Retry-After
until the next UTC midnight, and reserves nothing. /health/deep shows credits_today: a run
in flight counts its whole reservation, and a finished run, once settled, only the provider
credits its calls spent (0 when it bought nothing). While the video search provider is refusing our requests,
a start is 503 with code search_unavailable and a Retry-After of about a minute, and
reserves nothing: the run would have failed. It clears by itself once the provider answers
again.

A finished run returns at once, and an unknown one is 404 at once. One account may have
10 waiting requests at a time; beyond that the wait is 429 with
Retry-After. Without ?wait the run comes back at once, so polling every few seconds works
too.

Pass the last progress.updated_at as ?since=<timestamp>&wait=N to return on a
progress change or completion, whichever comes first. URL-encode the timestamp (including
its + timezone). since must be an ISO 8601 timestamp with a timezone; malformed values
are 422 invalid_request on REST and MCP. Without since, waiting is unchanged. MCP get_run
takes the same since string with wait_seconds. Progress writes remain at most once a second,
except that a new card (or the end of the run) is written, and a waiting call answers, at once.

Counts mean: found has a view count in the pool; above_floor has been caption-judged at
or above the floor; on_topic passed the caption judge, including below-floor fill;
read completed transcript and screen enrichment; held was chosen; written was successfully
described; wanted is the requested count. Reused clips count as read when inspected.

status goes queued, running, then done or failed. If the server restarts or is updated
while a run is in flight, the run goes back to queued once (progress message "resuming
after a server restart") and carries on with the same reservation, the same reading of
your topic and the clips it already found; keep waiting as for any queued run. It is charged only what the resumed run itself used,
never more than credits_reserved; what the stopped part cost is ours. A run that stops a
second time fails and is refunded.

charged is what you pay: 0 on a failed run and on a run that found no hooks (within the
daily allowance of free empty runs). credits_ig and credits_tt are the provider credits the
run used so far on Instagram and TikTok: they grow while the run is in flight, stay on a failed
(refunded) run, and on a resumed run include what the stopped part used, so they can be
more than charged.
progress says what the run is doing:

    progress          {"stage", "message", "updated_at"}, plus "counts" once the research
                      reports them and "preview" while it holds a hook
    counts            {"found": int, "above_floor": int, "on_topic": int, "read": int,
                       "held": int, "written": int, "wanted": int}, plus "talking" (clips
                       checked so far that show a person talking) once the research
                       reports it (since 2026-09-29). Long form and Packaging runs also
                       report "channels" (measured so far), "outliers" and, once a channel
                       is measured, "measured" and "beat" (since 2026-10-08): the videos
                       held against their own channel and how many beat the bar, the set
                       report.landscape counts, so "beat" is the number to show as "beat
                       their channel" and the finished run ends on the same one. "outliers"
                       also counts a channel's other uploads that beat it; keep it for
                       old code. On Packaging, "read" counts the thumbnails looked at, and
                       stage "writing" starts only with the playbook.
    preview           hooks written so far in delivery order, at most wanted entries:
                      [{"hook": str|null, "platform": "tiktok"|"instagram", "creator": str,
                        "views": int, "topic": str|null, "cover_url": str|null}]
                      Since 2026-10-07 each entry is a card to read and play while the
                      run goes on: it also carries "why" (why the opening holds a viewer),
                      "hook_type", "watch_url", "player_url" (the 9:16 iframe src the
                      finished hook gets) and "thumb_url" (the cover as a JPEG from this
                      API, no key; use it rather than cover_url).
                      Only on a running run with a hook written; gone once done or
                      failed, when the full hooks are on the run. Counts remain.
    feed              the live research wall (since 2026-09-30): the clips the run is
                      working on right now, newest first, at most 24:
                      [{"key": str, "platform": "tiktok"|"instagram", "creator": str,
                        "views": int|null, "state": "found"|"reading"|"talking"|"passed",
                        "thumb_url": str|null, "line": str|null}]
                      key is opaque and stable per clip within the run. thumb_url is an
                      absolute URL of the clip's cover as a JPEG (https://api.hookdetector.com/v1/runs/<run_id>/
                      thumbs/<key>): no key needed, so an <img> loads it; 404
                      thumb_unavailable once the run no longer shows the clip. line is the
                      banner or the opening words, only once the judges passed the clip and
                      it is on its way to delivery. state "passed" means dropped (off
                      subject, other language, not needed); a carousel is never in it.
                      Only while a running run shows a clip; gone once done or failed.
    scan              Long form and Packaging only (since 2026-10-08): the videos the run
                      is looking at while it works, for a wait screen:
                      {"tiles": [{"v": str, "s": str, "x": float|null}],
                       "lanes": {"found": int, "on_topic": int, "measured": int,
                                "beat": int, "reading": int, "ready": int}}
                      tiles: at most 60, in the order the run first saw each video (oldest
                      first); a tile never changes place. v is the YouTube video id (11
                      characters of A-Z a-z 0-9 _ -): load its picture from
                      https://i.ytimg.com/vi/<v>/mqdefault.jpg yourself, nothing goes
                      through this API. s: found (a search returned it), on_topic or
                      off_topic (the title judge), measured (its channel's usual is known
                      and it is under the bar), beat (its views are at least the bar times
                      its channel's usual), reading (its transcript or thumbnail is being
                      read), ready (written up, it is a result), passed (dropped); read an
                      unknown s as found. x: how many times its channel's usual, one
                      decimal, once known. lanes.measured and lanes.beat are
                      counts.measured and counts.beat. Only while a running run has seen
                      a video; gone once the run is done or failed.
    stage             one of: queued, starting, reusing, searching_instagram, searching_tiktok, judging, transcribing, writing, searching_youtube, saving, done, failed, other
                      ("other" is any step not in the list; treat it as working)
    message           one short human sentence, for example "searching TikTok, round 1"

When status is "done", `hooks` holds the result. Each hook has:

    hook_id           use it with the hook routes below
    hook              the exact opening line, as spoken or shown, verbatim
    catchy_line       the most quotable line anywhere in the clip, verbatim
    main_idea         one sentence on what the clip argues
    why_it_travelled  why the opening stops the scroll; since 2026-10-02 the same text as
                      mechanism (below), never a view or follower count
    topic             three to six words naming the narrow subject
    onscreen_text     text shown on the video: on TikTok, the creator's own text-tool text
                      when there is some (exact, since 2026-09-28), else what a vision model
                      read off the opening frames (on hooks found before 2026-09-26, every
                      slide of a photo post in order)
    transcript        the audio transcript, which can include lyrics
    transcript_kind   "speech" (a person talking carries the message), "music" (lyrics, a
                      trending sound, background audio), "none" (no transcript), "other"
                      (anything else, such as a transcriber's error message). Null on
                      older hooks or when unknown. Included in every export format.
    heard             since 2026-10-26: false when our speech service could not hear the
                      clip right now, so it shows no spoken words (transcript null) and
                      the done run's message counts them; true otherwise and on older
                      hooks. In the JSON export, not the CSV
    language          the language or dialect the clip was judged to be in, named in
                      English and as precisely as it was judged ("Moroccan Darija", not
                      "Arabic"); a locale run names a clip with whole sentences in a second
                      language "X with Y" ("Moroccan Darija with French"). Null on hooks
                      found before this field. In every export format.
    signals           how far the clip travelled beyond its creator, from the platform's
                      own numbers: followers, shares, saves, comments, posted (YYYY-MM-DD),
                      reach (views over followers: 12.5 is twelve and a half times the
                      creator's audience), shares_per_1k and saves_per_1k. TikTok carries
                      them all, Instagram at most comments and posted; a key appears only
                      when the platform stated it; null when none. Since 2026-09-28 hooks
                      are ranked by views, reach and shares and saves per view together, so
                      a small creator's breakout can sit above a large account's routine post.
    video_id          the platform's id for the clip (TikTok id, Instagram shortcode)
    player_url        a vertical player to put in an iframe: TikTok's official player, or
                      Instagram's /reel/<code>/embed/. null for an id that is not the
                      platform's shape, or for a TikTok photo post found before 2026-09-26
                      (slide_count is set); no run since then delivers one
    aspect            "9:16", the frame to size that iframe to
    still_url         the card image as a JPEG served by this API (https://api.hookdetector.com/v1/hooks/<id>/still).
                      Use it in an <img>: it needs no key and loads on any page, where the
                      platforms' own image links expire or refuse other sites. A TikTok
                      photo post found before 2026-09-26 (no player) gets its first slide.
    media_url         our own player's source (https://api.hookdetector.com/v1/hooks/<id>/media): put it in a
                      <video src>. It redirects to the clip's original file on TikTok's or
                      Instagram's CDN (seeking works, no key, nothing stored). null for
                      YouTube Shorts (use player_url) and photo posts; a 404 media_unavailable
                      or 503 media_busy from it means show player_url instead.
                      A 404 still_unavailable means no source had a picture; such an older
                      photo post may show its picture a few seconds later, so retry once
                      after about 10 seconds
    slide_count       always null on hooks found since 2026-09-26; the slide count of a
                      TikTok photo post on older hooks
    format            what kind of clip it is: "talking_head", "podcast", "interview",
                      "stage" (stand-up, a keynote, a lecture: a person on camera
                      talking), or "voiceover", "text_on_screen", "broll", "skit",
                      "lipsync", "trending_sound", "slideshow", "call_recording" (a
                      recorded call or voicemail), "live_interaction" (the creator with
                      real people in the scene, not the viewer), "other". Null on hooks
                      found before 2026-09-29; read an unknown value as "other". In every export.
    section           always "main". Bonus was removed on 2026-10-08; the CSV keeps its
                      `section` column and the run keeps an always-empty `bonus`.
    creator_country   the country of the creator's TikTok account, ISO alpha-2 ("MA"), as
                      TikTok states it (the account's country, not GPS). Always null on
                      Instagram, which states none, and on hooks found before 2026-09-30
    place             the place the creator tagged on the post (at most 80 characters),
                      null when untagged, as most posts are
    place_country     the tagged place's country, ISO alpha-2, only when the platform
                      states it; null otherwise. None of the three is ever guessed. All
                      three are in the JSON and Markdown exports, not in the CSV
    banner            the banner hook: the title-style text the creator placed on the
                      video to hook the viewer (a headline, a "POV:", a question, a list
                      title), verbatim, one line of at most 200 characters. Null when the
                      clip has none; running subtitles of the speech, usernames,
                      watermarks and a lower third naming the speaker are never a banner.
                      Null on hooks found before 2026-09-30. `onscreen_text` still holds
                      all the text read on screen. In every export (the CSV since
                      2026-10-02)
    match             on a run with a language or a country: "exact" when the clip is
                      about the subject itself, "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 hooks found before
                      2026-09-30 and on runs with no language or country. Since 2026-10-02
                      no clip that drops the audience or field the subject names ships in
                      either list. In every export ("Match: close match" in Markdown)
    style_match       since 2026-10-04, on a run whose request asked for a kind of opening
                      ("controversial hooks", "question hooks", "storytime"): true when
                      the hook opens that way (its hook_type is one asked), false for a
                      strong hook on the subject that opens differently, delivered after
                      the ones that match. Null when no kind was asked. The run's
                      `understood` says what was asked (subject, styles, style_other,
                      wants, core, audience, neighbours, language, country)
    virality          since 2026-10-01: how viral the clip is, 0 to 1 (0.58 is 58 out of
                      100). Since 2026-10-02 on one fixed scale, so the same clip scores the
                      same in every run and two runs compare: the outlier when known
                      (replacing reach), freshness, travel (shares and saves per 1,000
                      views), an own-sound reuse bonus and a paid penalty, a missing one
                      counted as no signal. virality_why is one line naming the strongest
                      signal ("31x this creator's usual", "1.2M views in 4 days"), never
                      empty when virality is set. Null on older hooks
    hook_type         since 2026-10-02: the device the opening uses: curiosity_gap,
                      contrarian_claim, specific_number, identity_callout, stakes_threat,
                      promise_payoff, pattern_interrupt, story_open, question,
                      direct_command or other (hook_type_other then names it in a few
                      words). Read an unknown value as other
    mechanism         since 2026-10-02: why the opening stops the scroll, two short
                      sentences quoting the clip's own words (each quote checked word for
                      word against what was said or shown) and the question the clip
                      pays off
    visual_hook       what the banner or other on-screen text adds to the spoken opening,
                      or null
    audience, template, steal_it
                      the viewer this opening stops; the hook as a fill-in structure with
                      {placeholders}; one sentence on reusing the move in another niche.
                      All seven analysis fields are null on hooks found before 2026-10-02
                      and are in every export (appended at the end of the CSV)
    outlier           views divided by creator_median_views, the creator's usual views per
                      video (the median of their recent videos, pinned excluded): 31.2
                      is 31 times what this creator normally gets. outlier_basis says how
                      the baseline was measured: "median_views", or "likes_per_video" when
                      TikTok's likes-per-video proxy was used. Null when the creator's
                      baseline was not priced for this run
    posted_at, age_days, views_per_day
                      when the clip was posted (ISO 8601, exact when the platform gives
                      it), days since then at delivery, and views divided by that
    duration_s, paid, sound_reuse, own_sound, hashtags
                      the clip's length in seconds; whether the platform labels it an ad,
                      a paid partnership or branded content; how many videos reuse its
                      sound and whether the sound is the creator's own; the post's
                      hashtags (at most 20, without the #). Null when unknown
    views, likes, creator, platform ("tiktok", "instagram" or, since 2026-10-01,
    "youtube": YouTube Shorts only, never long-form; its watch_url is always
    https://www.youtube.com/shorts/{id}), watch_url, cover_url, above_floor, found_by,
    caption, verdict

Patterns (since 2026-10-01): a done run also carries `patterns`, up to 3 opening
structures SHARED by at least two of the deck's hooks (a device, never a topic), from the
delivered deck (`hooks`). Since 2026-10-02 the hooks are grouped
by their `hook_type` in code and one cheap model call names each group and writes its
template (at least 3 literal words) and why, in the deck's language; they are computed
before the run is marked done, so `done` carries them. The most shared first, then by the
summed virality of their hooks: each {"name", "template" (the structure with
{placeholders}), "why", "hook_ids" (the delivered hooks using it), "count" (2 or
more)}. Null on older runs, when the call failed on a deck without hook types, and when no
structure is shared (stats.patterns_note then says so in one line); the run itself is never
failed by it.

Talking heads only (since 2026-09-29): `hooks` holds only clips where a person on
camera is talking to the viewer or in conversation (talking head, podcast, interview,
street interview, a vlog to camera), and the words that make the hook are theirs. A run
asked for N hooks aims at N of them; when it finds fewer it says so in `outcome` and never
fills `hooks` with clips that do not talk. A clip where nobody talks (text on screen, a
voiceover over footage, b-roll with captions) is dropped and never written up: Bonus, the
separate list of those clips, was removed on 2026-10-08, and `bonus` stays on the run
object, always []. `stats.talking` says how the run told them apart:
{"checked", "talking", "not_talking", "vision_calls", "certain_by_text"}.

No carousels (since 2026-09-26): a run delivers single videos only, TikTok videos and
Instagram reels. TikTok photo posts (slideshows) and Instagram carousels are dropped at
search, before any credit is spent on them, and never fill a short run.
`stats.dropped_carousels` counts the ones a run met. Hooks found earlier keep their fields
and their still.

When transcript_kind is music, none or other, hook and catchy_line come from on-screen
text only; such a clip with no on-screen words has neither and ranks after clips with
words. catchy_line is picked by number from the clip's own numbered sentences (said and
shown, never the caption), so it is word for word; it repeats the hook only when the
hook is the only line. In a run with a language or country it may be the exact run of
that sentence worth quoting on its own, still word for word. Cross-posts of one clip are delivered once, and their handles
share the per-creator cap: at most 2 clips from one creator, 1 when 10 or fewer are asked.

`hook` and `catchy_line` are always word for word from what the clip says or shows. A
hook with no transcript and no on-screen text has both null: there is nothing to quote,
and we will not invent a line from a caption. `hook` is also null when the clip's real
opening could not be found word for word. `catchy_line`, when the model paraphrased it,
is replaced by the clip's own sentence it paraphrased, and is null only when no sentence
is close.

    GET https://api.hookdetector.com/v1/runs?limit=20  your runs, newest first, limit 1 to 100

Every run, in GET /v1/runs/{run_id} and in each GET /v1/runs item, carries
`conversation_id`: the chat conversation it belongs to, or null. A client that lost the
conversation id of a chat turn (a page refreshed during POST /v1/chat) finds it on the
newest run.

Every run (the 202 start response, GET /v1/runs/{run_id} and each GET /v1/runs item) also
echoes `language` and `country` as asked, or null. A finished run's stats carry `locale`
({"subject", "language", "country", "exclude"}: what the first step understood, exclude
being the languages and dialects it ruled out), `rejected_after_reading` (clips the judges
refused after reading what they say and show: another language or dialect, or off topic)
`dropped_other_country` (TikTok rows placed in another country, dropped for free) and
`dropped_other_language` (hooks whose own write-up placed them outside the language asked
for, dropped before delivery) and `dropped_carousels` (TikTok photo posts and Instagram
carousels met at search and dropped unread, free: a run delivers single videos only since
2026-09-26). Stats also carry `credits_lent_to_tiktok`: when Instagram finds nothing it can rank (its
topic pages rarely exist for non-English phrases), the credits it cannot use search and
read TikTok instead. Lent credits are counted in `credits_tt`, not `credits_ig`. The run
never spends more than it reserved. `search_breadth` says how widely a run searched: a
request of up to 5 hooks searches the subject plus 6 phrases per platform per round, a larger
one 30 on Instagram and 12 on TikTok, and Instagram's reels route is bought only when its
popular route found too few clips to rank (`instagram_reels`: bought, skipped).
`onscreen_sources` says where each clip's on-screen text came from: `sticker` (the text the
creator typed with TikTok's own text tool, exact, read from the search row) or `vision` (read
off the clip's cover frames by a vision model).

Why a run came back short: `stats.rejections` counts the clips that were refused, each
once, in one of `other_country` (TikTok clips placed in another country, dropped unread and
free), `off_subject_or_locale` (read, and the judge refused them: not about the subject or,
on a run with a language or country, not in it; one verdict answers both),
`other_language` (their own write-up placed them in another language or dialect, with
`languages` counting which), `no_words` (nothing said or shown, on a run whose language
rules that out) and `other` (a check that failed). Since 2026-10-08 a run also carries
`stats.held_back`: what kept clips out of its deck, by reason, each clip once, in
`proof` (on the subject, but no sign it travelled: a TikTok clip with fewer views than its
creator has followers and no outlier of 2x, a clip under the view floor without proof, or
one doing less than its creator's usual), `relevance`, `language`, `no_words`, `supply`
(on the subject, never read because the search ended first; counted only on a short deck)
and `other`. A finished run that delivered fewer
hooks than asked for, or none, carries `outcome`: one plain paragraph saying why, what to
try next, and whether an empty run was free, for example "No hooks. 17 clips on topic by
their captions were refused after reading: 17 judged not about home workouts or not in
Quebec French from CA. 302 clips from outside CA were set aside. Try: run it without the
country, or name the language or variety another way, or leave it out. It was free: a run
that finds no hooks is not charged." On a run that carries `held_back` the paragraph's
second sentence is one line from it, for example "24 of 30 hooks. 6 more clips were on the
subject but had no sign they travelled." A full run gets no advice: its `outcome` is null, or
one sentence when some of its hooks are under the view floor because the country filter
set most clips aside ("1 of these hooks has under 50,000 views; 277 clips from outside MA
were set aside."). `outcome` is null on a failed run (read `error`) and a run in flight.

When the language asked for is a dialect (a spoken variety whose speakers write another
standard, such as Moroccan Darija, Egyptian Arabic or Swiss German, or a mix such as
Hinglish; a country's own standard such as Brazilian Portuguese or pt-BR is not), a TikTok
clip whose words came from TikTok's automatic captions, or that has none, is heard
again from its first minute by ElevenLabs Scribe v3 speech recognition (OpenAI's recogniser,
measured first on Moroccan Darija, was coherent on 13 of 13 clips, 4 of which TikTok's
captions garbled end to end); stats carry
`transcription` ({"model", "dialect", "clips", "seconds", "usd_estimate", "failed",
"skipped_over_cap", "cap_seconds"}; the ceiling grows with the hooks asked, three times as
much at 30 as at 10). That costs you nothing: credits count search calls only.

    GET https://api.hookdetector.com/v1/hooks/{hook_id}  one hook, every field

A failed run's `error` says why in plain words and ends with "(request id ...)", the
X-Request-Id of the call that started it; the run also carries it as `request_id`. Quote
it if you report a problem.

A run that finds no hooks fails, as our fault and refunded, only when a failure on our side
could have emptied it: the search found no clips because its calls failed, a topic or
language check failed so clips went unchecked, no clip could be read, or every write-up
failed. A passing failure that decided nothing does not: the run finishes done, with no
hooks and an `outcome` that says why.

## Export a run

    curl -OJ "https://api.hookdetector.com/v1/runs/$RUN_ID/export?format=csv" -H "authorization: Bearer $KEY"

Add `&bom=true` for a csv a person will open in Excel: the file then starts with the UTF-8
byte-order mark, so curly quotes, emoji and accents read right. Leave it off when a program
reads the file (Python's csv with plain utf-8 would read the mark into the first header).

format is csv (default: one row per hook, opens in any spreadsheet; `video_id`,
`player_url` and `still_url` come last, after `hook_id`, so a sheet can show and play each
hook), json (the full hook
objects) or md (Markdown notes, one section per hook). The file comes as an attachment
named hookdetector-<run_id>.<ext>. CSV cells that a spreadsheet would run as a formula
(starting with = + - @, a tab or a carriage return) are prefixed with a quote. A run still
queued or running is 409 run_not_finished. Free.

## Long form and packaging (long-form YouTube only, since 2026-10-07)

Two more kinds of run. Both search YouTube's long-form videos (never Shorts, TikTok or
Instagram), keep only OUTLIERS, and never deliver a video posted before 2023-01-01.

An outlier is a video whose views are a multiple of what its own channel usually gets:
views divided by the median views of the channel's recent long-form uploads. `min_outlier`
(1.5 to 100, default 2) is the bar; a video under it is
never delivered, however many views it has. A search row's date is approximate ("3 years
ago"), so a video the search cannot place on one side of 2023 is dated exactly before it
is delivered (`posted_exact` true).

    curl -X POST https://api.hookdetector.com/v1/longform       -H "authorization: Bearer $KEY" -H "content-type: application/json"       -H "Idempotency-Key: $(uuidgen)"       -d '{"topic": "cold plunge", "count": 8}'

    curl -X POST https://api.hookdetector.com/v1/packaging       -H "authorization: Bearer $KEY" -H "content-type: application/json"       -H "Idempotency-Key: $(uuidgen)"       -d '{"topic": "cold plunge", "count": 12, "ideas": 6}'

Both answer 202 with a run_id, exactly as POST /v1/research does (same Idempotency-Key
rules, same 402, 403, 429 and 503 refusals, nothing reserved on a refusal). Then
GET /v1/runs/{run_id}?wait=55 until status is done or failed (how long these runs
take has not been measured yet: keep polling, never assume a time). The
run object is the one every run has, with kind "long" or "packaging", `hooks` and `bonus`
always empty, and three more keys:

- `finds`: the results, ranked, strongest outlier first. [] until the run is done; while
  it runs, `progress.items` holds the finds written so far as cards (the fields a list
  shows: video_id, title, channel, watch_url, thumbnail_url, views, duration_s, age,
  outlier, outlier_score, outlier_tier, and `hook` or `thumbnail_text`; no find_id yet) and
  `progress.scan` the videos the run is looking at. The whole find, with its intro and
  analysis, arrives in `finds` when the run is done.
- `report`: what the run concluded beyond its finds (below). Null until done.
- `options`: the options the request set.

A link instead of a subject. `topic` may be a YouTube address:

- a channel's (https://www.youtube.com/@name, or just @name; /channel/UC... works too):
  the run returns that channel's OWN outliers, its recent long-form uploads (the newest
  page, about 30) that beat the channel's usual without themselves. One provider call, no
  search and no title judge; a small channel's breakout counts whatever its views.
- a long-form video's (https://www.youtube.com/watch?v=..., youtu.be/...): the run returns
  that one video, whatever its multiple (`requested` is 1), held against its channel when
  the channel can be measured. Two provider calls.

`options.link` on the run says "channel" or "video". The 2023 floor holds for both; a
Short's address, a playlist or another site is 422 naming `topic`. No openers or ideas are
written for a link (there is no subject to write them for): use POST
/v1/finds/{find_id}/remix on a find to write for your niche.

Body, both: topic (3 to 500 characters), count (long 1 to 30,
default 8; packaging 1 to 30, default 12), language
(optional: the language the videos should be spoken in; read from the topic when left
out), country (optional ISO alpha-2: where YouTube is searched from; it steers, it does not
filter), min_outlier, posted_within_days (30, 90, 365, 730, or null for everything since
2023), channel_size (small, medium or large: only channels of that size, by what their
uploads usually get, under 20,000 views, up to 200,000, or more; so a
small creator sees breakouts from channels their own size) and reuse (default true: start
from the videos your last long or packaging run on this topic bought within a week, so
the second tab on a topic costs little, and a video you already had read is delivered
from that read with today's numbers: `analysis_from_earlier_read` true; only a read with
real content, of an opening in a language this request takes, or of the thumbnail YouTube
serves now, and only search rows the provider answered under a week ago). Long form
also takes intro_seconds (20 to 120, default 60) and openers
(0 to 6, default 3); packaging takes ideas (0 to 10,
default 6).

Every find, either kind: find_id, run_id, kind, rank, verdict, video_id, title (as YouTube
shows it, word for word; runs of spaces read as one),
channel, channel_handle, watch_url, player_url (an iframe src, 16:9), thumbnail_url and
thumbnail_urls (YouTube's image host, every size, best first; a size a video lacks answers
404), views, likes and comments (when YouTube gave them), duration_s (always over 180),
posted_at and posted_exact, age_days, views_per_day, channel_median_views and
baseline_videos (how many uploads that median is of), outlier (28.2 means 28 times the
channel's usual; the channel's usual is measured without the video itself), why (the
outlier in words), found_by (the search that surfaced it), outlier_score (the
video on one fixed scale, 0 to 100: its outlier, its reach, how fresh it is and its likes
for every 1,000 views, placed between two fixed anchors. Nothing else a run found moves
it, so finds from different runs rank together; it moves only with the video's own
numbers and age), outlier_tier (outlier, strong from 5 times, breakout from 10),
channel_size (small, medium or large), seen_before (an earlier run of yours on this tab
already found this video; a keep or reject made then is already on it),
likes_per_1k and comments_per_1k, style_match (when the request asked for a kind of
opening or title, "question hooks" or "how-to titles": whether this one is that kind, the
matches delivered first; null when it asked for none), angle (the specific angle the video
takes on the subject), language and analysed (false when the model could not analyse
it, or answered without the analysis itself: the find is still real, its analysis fields
are null or partial).

A long find adds the opening as it was SAID, cut by the transcript's own clock: `intro`
(the first intro_seconds as lines of n, t in seconds, text) and `intro_text`, always whole.
Inside it is the hook, cut by the analysis' own beats and never the opening itself:
`hook` (verbatim: the lines marked as the hook, ending on the last sentence end that keeps
it inside 25 seconds and 60 words, a sponsor read or a greeting at the front left out),
`hook_words`, `hook_start_s` and `hook_end_s` (the seconds it runs between, to a tenth,
never null; inside a line they are estimated at the opening's own pace), `hook_lines`
(how many lines of `intro` it reaches) and `hook_seconds` (the same number as
`hook_end_s`, for older readers). `auto_captions` is true when the opening has almost no
punctuation: its sentences are not marked and names may be misheard, so the hook ends where
the analysis' beat ends. `about_subject` is yes or partly (null for a channel or video link
and when the model gave no answer): the same call that analyses the opening also says
whether the video is about the subject, and a video it says is not is dropped and its seat
read for the next one (`stats.skipped.off_subject`, and `stats.about_subject` counts
every answer). And the analysis: hook_type (the hook types of a short hook), mechanism
(why it holds, quoting the opening word for word; a quote not in the opening takes its
sentence with it), promise,
open_loop, title_link (how the first lines pay off the title), beats (the opening in
consecutive parts: from, to, beat, does), opens_with (how the first seconds begin:
cold_open, greeting, teaser, question, sponsor, other), format (the kind of video),
template, steal_it and audience. A long run's
`report` holds three things. `patterns`: the opening types at least two finds share
(hook_type, count, video_ids, template, example, and why once the run could say it).
`shape`: how the openings are built,
counted from the finds and never estimated (videos, mapped, hook_seconds, how long the
hook runs from `hook_start_s` to `hook_end_s`, and hook_words, as medians; `beats`: each beat with the count of openings using it and the median second
it starts_at, `sequence`: the order of beats most of them share, with its count, and
`opens_with` and `formats`: how the openings begin and what kinds of video they are, each
name and count).
`openers` (hook, then, hook_type, based_on) and `openers_label`: openings WRITTEN for your
topic from those structures; openers_label is always "Written by Hook Detector from the structure of these real openings". Show it with
them. An opener is never a find, and one that is a real opening's words (the same words
under other punctuation, or most of it lifted in one piece) is dropped.
`landscape`, on both kinds: the subject at a glance, counted from the videos the run held
against their own channel and never estimated (videos, channels, bar, outliers and their
share, strong, breakouts, small_channel_outliers, recent_outliers: posted in the last
year, median_views, and beat_2x, beat_5x, beat_10x: how many beat their channel by that
much whatever bar the run asked for, so an empty run shows what a lower bar would find);
null when none was measured.

A packaging find is the title and the thumbnail as YouTube shows them: `title` is
verbatim, and `thumbnail_url` is the size YouTube really served for this video, the same
picture the analysis looked at (`thumbnail_checked` true; false when no size could be
fetched and the link is the usual address), `thumbnail_sha256` (a digest of that picture:
a later run reuses this analysis only while YouTube serves the same one) and `analysed_at`
(when it was looked at). It adds what the two do together:
title_device, title_template, title_chars, cut_on_phone (true when the title is longer than
60 characters, where a phone roughly cuts a title; approximate, because YouTube publishes no
limit and the cut moves with the screen, the font and the letters), 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), title_overlap (the share of the
thumbnail's words that are also in the title, 0 to 1, counted in code; null when there are no
words or they are in a script the title does not use; where it can be counted the role
follows it: repeats_title at 0.7 or more, adds_to_title under 0.3, and between those the
model's reading stands), thumbnail_subject, thumbnail_faces,
thumbnail_emotion, thumbnail_colors, thumbnail_composition, thumbnail_devices, gap (what the picture shows that the title does not say, and the
question that leaves), promise, steal_it and audience. on_subject says whether the look,
told the run's subject, judged the package to be about it: yes, or partly (it covers the
subject as one part of something broader). A package judged no is dropped and the next
candidate takes its slot, so no delivered find carries it; on_subject is null on a run for a
channel's or a video's address, when the look gave no usable verdict, and on an analysis an
earlier run wrote (its subject may have been another). A look that did not come back whole is
asked once more; if it still fails, the next candidate takes the slot, and a package whose
look failed is delivered unread (analysed false) only when no other candidate could fill
the slot. A packaging run's `report` holds
title_patterns and thumbnail_patterns (what at least two packages share: name, template or
description, why, video_ids, count), `numbers` (the packages counted: title_chars and
title_words as medians, titles_with_number, titles_with_question, titles_cut_on_phone with
phone_title_chars, thumbnails_with_text and
thumbnail_words, thumbnails_with_face and text_roles over the `analysed` ones, and the
title_devices, thumbnail_devices and emotions that repeat, each name and count; age_cohorts
holds the same counts for the packages posted in the last split_days days (recent) and for
older ones, and counts apart those with no known age as undated), `ideas` (title, thumbnail, thumbnail_text: the
words to print on it, pattern, based_on) and `ideas_label`. The ideas are WRITTEN for your topic from those patterns; ideas_label is
always "Written by Hook Detector from the patterns in these real packages". Show it with them. An idea is never a find, and one whose title
is a real one's words, or is over 70 characters, or has more than 5 words for its thumbnail,
is dropped. `playbook_note` is one line when the patterns could not
be written.

    curl -X POST https://api.hookdetector.com/v1/finds/$FIND_ID/decision -H "authorization: Bearer $KEY"       -H "content-type: application/json" -d '{"verdict": "keep"}'
    curl -X DELETE https://api.hookdetector.com/v1/finds/$FIND_ID/decision -H "authorization: Bearer $KEY"
    curl "https://api.hookdetector.com/v1/finds/keeps?kind=long" -H "authorization: Bearer $KEY"
    curl "https://api.hookdetector.com/v1/finds?kind=packaging&sort=score&q=cold" -H "authorization: Bearer $KEY"
    curl https://api.hookdetector.com/v1/finds/$FIND_ID -H "authorization: Bearer $KEY"
    curl -X POST https://api.hookdetector.com/v1/finds/$FIND_ID/remix -H "authorization: Bearer $KEY"       -H "content-type: application/json" -d '{"niche": "teeth whitening", "n": 2}'

Keep, reject, undo and the kept list work on finds as they do on hooks, on their own
routes, with one difference: a verdict is the VIDEO's on that tab. Keeping a find keeps
every find of the same video you have there, so a later run that finds the video again
shows it already kept, and GET /v1/finds/keeps lists a kept video once. GET
/v1/runs?kind=long (or packaging, or short) lists one kind. GET
/v1/runs/{run_id}/export gives a long or packaging run as csv, json or md too.

The index, GET /v1/finds (MCP list_finds): every video your long and packaging runs found,
one entry a video on each tab (its newest read). sort is score (default), outlier, views
or newest. 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"). tier (breakout, strong, outlier),
min_score (0 to 100) and device (a hook_type, a title_device or a thumbnail device)
narrow it. `total` counts every match, on any page. Free: search what you already paid
for before starting a new run.

Make it mine, POST /v1/finds/{find_id}/remix (MCP remix_find): body niche and n (1 to 5,
default 3). From a long find it writes openings for your niche (hook, then,
kept_structure) on that opening's template and order of beats; from a packaging find,
packages (title, thumbnail, thumbnail_text, kept_structure) on its title template and its
thumbnail's composition. Always under `label`; one that is the real find's own words is
dropped; never added to a run, a keep or an export. 1 credit a call, refunded when the
model does not answer (503 model_unavailable), and when every one it wrote broke a rule or
it declined the content (422 remix_not_possible, the detail says which rules; waiting does
not help, another try or another niche may); limited per account per hour (429).

Write my intro, the same call with {"mode": "intro", "video_brief": "<your video in a few
sentences, 10 to 600 characters>"} (MCP remix_find with mode and video_brief; a long find
only, a packaging find or a hook is 422; niche and n are not used): your own intro for the
video you describe, in that real opening's structure. `written` holds one object with a
beat for each beat of the real opening, in order: beat and does (what the real one does),
from_s and to_s (seconds into the video), seconds and words_budget (the seconds times the
opening's measured words a second, from the find's own timing, never the model's), say (the
words to say, with {placeholders} for what only you know: a name, a result, a number you
did not write), words, placeholders, suggested_on_screen and suggested_broll (suggestions,
never part of what is said). Also seconds (where the intro ends, never past the real
opening), timing (measured, or estimated when the captions carried no clock), kept_structure,
placeholders (every one to fill in, once) and numbers_to_placeholders (numbers the model
wrote that your video_brief did not give: each is now {number}). The answer carries mode
"intro", video_brief and niche null. One credit, the label, the idempotency, the refund and
remix_not_possible are the same; a beat that copies the real opening, repeats another or
runs over its words_budget by a quarter drops the whole intro. List and read it back with
list_remixes and get_remix: each has mode "intro".

What they cost: a long run reserves up to 90 credits for 20
videos or fewer and 5 more for each video above that, up to 140 credits
for 30; a packaging run up to 70 credits for 24 packages or
fewer and 3 more for each package above that, up to 88 credits for
30 (both less on a smaller balance, down to 25), and each is charged only
the provider calls it made: the searches, one call per channel measured, and for long form
one per transcript read (and one for each video that had to be dated exactly). Looking at
a thumbnail costs no credit. A run of 30 has not been measured live yet: the
reservations above are sized from the study's estimate (75 to 95 credits for 30 videos,
55 to 62 for 30 packages), and what a run really used is `credits_yt` and `charged`,
its provider calls by route and their seconds are `stats.calls_by_route` and
`stats.latency`. A failed run costs nothing, and a run that finds nothing is
free inside the same allowance a hook run has (past it, `outcome` says the run was charged
and why). A done run with fewer finds than asked has `outcome`: the step that really
stopped it (nothing found, nothing recent enough, nothing on the subject, too few
outliers, the run's credits or time, or videos that could not be read) and what to try
next. A small reservation is split: the search takes at most about a third, so credits
remain to measure channels and read results. A run cut off by a restart of ours is failed
and refunded, never resumed: start it again. Starts of these runs are limited to
30 per account per hour (429 rate_limited), because a run on a subject you
already researched makes no provider call and is charged nothing.

## Pages

GET /v1/runs, GET /v1/keeps and GET /v1/conversations answer a page at a time with
`next_cursor`. Pass it back as ?cursor= for the next page; it is null on the last page.
limit is 1 to 100 (runs default 20, keeps 100, conversations 30). A cursor this API
did not issue is 422 invalid_cursor.

    curl "https://api.hookdetector.com/v1/runs?limit=50&cursor=$NEXT" -H "authorization: Bearer $KEY"

## Watch a clip in your own page

    curl https://api.hookdetector.com/v1/hooks/$HOOK_ID/embed -H "authorization: Bearer $KEY"

Returns official TikTok or Instagram embed HTML. `kind` is "embed", or "fallback" when the
creator has disabled embedding or the clip is a TikTok photo post found before 2026-09-26;
then show `thumbnail`
(the provider's, else cover_url, else the hook's still_url, never empty on a fallback)
and the transcript. `still_url` is always there. The HTML
is sanitized: no script (load https://www.tiktok.com/embed.js yourself, once per page), no
event handlers, no javascript: or data: URLs, and iframes only from TikTok or Instagram. For a
plain vertical player, put the hook's player_url in an iframe at aspect 9:16 instead.

## Keep what you want

    curl -X POST https://api.hookdetector.com/v1/hooks/$HOOK_ID/decision \
      -H "authorization: Bearer $KEY" -H "content-type: application/json" \
      -d '{"verdict":"keep"}'

    curl "https://api.hookdetector.com/v1/keeps?run_id=$RUN_ID" -H "authorization: Bearer $KEY"

verdict is "keep" or "reject"; run_id on /v1/keeps is optional. /v1/keeps returns
{"kept": [...], "count": <on this page>, "next_cursor"}.

To undo a verdict, clear it. The hook then has none, leaves /v1/keeps, and its export row
carries no verdict. Clearing a hook with no decision is the same 200, so a retry is safe:

    curl -X DELETE https://api.hookdetector.com/v1/hooks/$HOOK_ID/decision -H "authorization: Bearer $KEY"

It answers {"hook_id": "...", "verdict": null}; another account's or an unknown hook is
404 hook_not_found.

## Make it mine: lines written from a real hook's structure

    curl -X POST https://api.hookdetector.com/v1/hooks/$HOOK_ID/remix \
      -H "authorization: Bearer $KEY" -H "content-type: application/json" \
      -d '{"niche":"teeth whitening","n":2}'

Writes up to n (1 to 5, default 3) new opening lines for your niche that keep the real
hook's structure, the one or two devices that made it travel (named in kept_structure),
with the subject swapped for yours (MCP remix_hook). Each line is one spoken sentence (two
when the real hook is two) of at most 20 words (or the real hook's length plus 30
percent), never a stack of devices
the real hook did not have; the lines differ in angle. A line that breaks a rule is
dropped, so fewer than n can come back. It answers {"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 and 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 (a cheap model),
taken before the model is asked and refunded when it does not answer (503
model_unavailable, try again in a minute) and when it answers but every line it wrote broke
a rule or it declined the hook (422 remix_not_possible: the detail names the rules the
lines broke; waiting does not help, another try or another niche may); 402 insufficient_credits at a balance of 0; 404 hook_not_found for a
hook that is not yours; niche is 1 to 120 characters (422). Limited to
60 per account per hour (429). Needs research. In chat, "make hook 2 mine
for dentists" does the same and answers the lines labelled, the result under `remix`.

Send an Idempotency-Key header (MCP idempotency_key) to retry safely: the same key and body
within 24 hours answer the saved remix (header Idempotent-Replayed: true) and charge
nothing, even when two arrive at once; the same key with another body is 422
idempotency_key_reused. The answer carries remix_id and created_at. A paid remix is never
lost: GET https://api.hookdetector.com/v1/hooks/{hook_id}/remixes and GET https://api.hookdetector.com/v1/finds/{find_id}/remixes list
yours newest first, GET https://api.hookdetector.com/v1/remixes/{remix_id} reads one (MCP list_remixes,
get_remix), free; another account gets 404.

## Chat

    POST https://api.hookdetector.com/v1/chat  {"message": "<1 to 4000 characters>", "conversation_id": "<optional>"}
    GET https://api.hookdetector.com/v1/conversations?limit=30  your conversations, limit 1 to 100
    GET https://api.hookdetector.com/v1/conversations/{conversation_id}?limit=100&before=<earlier_cursor>  the newest messages of one, with their runs

A chat turn chooses "research" (starts a run in `run` and reserves credits), "clarify"
(one question, `run` null), or "answer" (discusses delivered hooks or explains the tool,
`run` null). Answers and clarification cost no credits. Every response has `suggestions`,
a list of zero to four short follow-ups; research returns []. A broad subject gets one
question with three angles and "Search it broadly" (always the last chip); a brief
with no subject gets example subjects and never that chip. Answer the question to research.
Answers refer to this conversation's completed decks and distinguish written adaptations
from real quoted hooks. Chat turns are limited per account per hour. A deck size typed
into the message ("..., 15 hooks", "5 ganchos") and a recency phrase ("this month", "last
week", in any language) set the run's count and posted_within_days. Asked to make one of
the conversation's hooks yours ("make hook 2 mine for dentists"), the turn writes lines
from that hook's structure (1 credit, as /v1/hooks/{hook_id}/remix does) and answers
them labelled, with the full result in `remix` (absent on every other turn). The chat body
also takes posted_within_days as the recency chip (7, 30, 90 or 365 sets it for this and
later turns and wins over a phrase; an explicit null, or 0, clears it; the conversation
carries it), seed_hook_ids for this turn's research, and count (1 to 30, since
2026-10-07): the deck size for a run this turn starts when the message states none.
An Idempotency-Key on a turn makes a retry safe whatever the turn did: the same key and
body within 24 hours answer the first turn again (its conversation, answer, run or remix),
with no model call, no new message and nothing charged, even when two arrive at once; the
same key with another body is 422 idempotency_key_reused. A conversation is read a page
of messages at a time, newest first: `earlier_cursor` (null on the first message) passed
as `before` gives the older page.

## Credits

One credit is one provider call. A run reserves up to 200 credits before it spends
anything and charges only what it used; the rest is refunded when it finishes. With less
than 200 left, a run reserves what you have, down to a minimum (40 by default), and
searches within it. A failed run costs nothing, and neither does a run that finishes with
no hooks, within two limits per account: 3 such runs per UTC day, and
500 credits waived that way in all. Past either, an empty run is charged what
it used, as any run is, and `stats.waiver_refused` names the limit. A free empty run records what it used in
`stats.credits_waived` and still counts it against a key's `credit_limit`. Rerunning the
same topic reuses rows you already paid for, so a second cut is close to free.

A run fails, and costs nothing, when a provider fails it: the search provider refusing
our key or not answering, or the language model not answering. Its error says so in
plain words; it is not a finding about your topic, so run it again later.

## Errors

Every error body is JSON: {"detail": "<one sentence>", "code": "<machine code>"}.
Branch on code; show detail to people. Every 422 also carries "errors", a list of
{"type", "loc", "msg"} where loc names the input that failed: ["body", "country"],
["query", "wait"], ["header", "Idempotency-Key"] or ["path", "run_id"]. Every response carries X-Request-Id: send your own (letters, digits, . _ : -, up
to 128) to trace a call, or read the one we made.

Every code, closed (a code you do not know: fall back on the HTTP status):

    invalid_request         422: the input failed validation; detail says which field
    invalid_cursor          422: the pagination cursor is not one this API issued
    idempotency_key_reused  422: this Idempotency-Key was used with a different body
    confirmation_required   422: DELETE /v1/account needs {"confirm": "delete my account"}
    invalid_api_key         401: the API key is missing, unknown or revoked
    invalid_admin_password  401: the owner's password sign-in (POST /v1/auth/admin-signin) failed; nothing was signed in
    invalid_exchange_token  401: the one-time sign-in token is unknown, used or older than 60 seconds; sign in again
    key_expired             401: the API key passed its expiry; create a new one with a key that still works (POST /v1/keys) or at hookdetector.com/account
    insufficient_credits    402: the balance is under the minimum a run reserves
    insufficient_scope      403: this API key lacks the permission the call needs; detail names it (read, write, research or admin)
    access_code_required    403: a new account needs a beta access code (access_code); ask for one at https://hookdetector.com/access
    invalid_access_code     403: the access code does not work (mistyped, used up, expired or revoked); ask for one at https://hookdetector.com/access
    admin_required          403: only the Hook Detector owner may call this route
    key_credit_limit_reached403: this API key has spent its credit_limit, or what is left of it is under the minimum a run reserves; nothing was reserved
    upload_instead          422: Edit Review could not read this link from our servers (YouTube refuses our downloads, or the video is private or removed); upload the file with POST /v1/review/edit/upload. Nothing was charged
    not_found               404: no such route
    run_not_found           404: no such run on this account
    job_not_found           404: no such background job on this account
    channel_not_found       404: no YouTube channel answers to that ref
    video_not_found         404: the linked video is private, removed or could not be found; the credits came back
    tracker_not_found       404: no such tracker you may read (private trackers are their owner's)
    alert_not_found         404: no such saved search on this account
    webhook_not_found       404: no such webhook on this account
    agent_not_found         404: no such agent on this account
    format_not_found        404: no such title format in today's list
    limit_reached           409: an account holds at most 20 trackers, a tracker at most 50 channels
    provider_unavailable    503: the YouTube data provider did not answer just now; retry after Retry-After. Nothing was charged
    hook_not_found          404: no such hook on this account
    find_not_found          404: no such find (a long-form or packaging result) on this account
    conversation_not_found  404: no such conversation on this account
    remix_not_found         404: no such finished remix on this account
    key_not_found           404: no active key with that id on this account
    access_request_not_found404: no access request with that id
    access_code_not_found   404: no access code with that id
    account_not_found       404: no account with that id (an admin route)
    media_unavailable       404: this clip has no video file to play (a YouTube Short, a photo post, a deleted or private post); play the official embed instead
    media_busy              503: the clip's video file cannot be looked up right now; play the official embed and try again after Retry-After
    thumb_unavailable       404: no picture for this research wall entry (an unknown key, or a run that no longer shows the clip)
    method_not_allowed      405: the route exists, the method does not
    conflict                409: the request conflicts with the account's current state
    key_limit_reached       409: the account already holds the most active keys it can
    last_active_key         409: the account's last active key cannot be revoked
    run_in_flight           409: a run is still in flight; wait for it before deleting the account
    remix_in_flight         409: a remix is still being written; wait for it before deleting the account
    remix_in_progress       409: a remix with this Idempotency-Key is still being written; send the same request again in a few seconds
    turn_in_progress        409: a chat turn with this Idempotency-Key is still being answered; send the same request again in a few seconds
    request_already_decided 409: the access request was already decided that way, or its code was used
    run_not_finished        409: the run is still in flight, so there is nothing final to export
    run_not_shareable       409: only a finished Short form run can be shared as a page (a failed run, a Long form or a Packaging run cannot)
    share_not_found         404: no shared page with that token (a wrong or mistyped link, or the account that shared it was deleted)
    remix_not_possible      422: the model wrote lines from this hook or find but none kept the rules (detail says which they broke), or it declined the content; nothing was charged. Not an outage: another try or another niche may work
    credits_below_zero      422: the owner's credit change would take the balance below zero; nothing changed
    payload_too_large       413: the request body is over the size cap
    rate_limited            429: a limit was hit; see Retry-After
    too_many_runs           429: the account already has the most research runs in flight it may; wait for one to finish (see Retry-After)
    internal_error          500: our fault; the detail names the request id. Credits a failed request held are returned automatically; GET /v1/usage shows the balance
    model_unavailable       503: the language model is unavailable; nothing was charged
    speech_out              503: our transcription (ElevenLabs Scribe v3) is out of credit, so a tool that needs a video's words cannot hear it now; nothing was charged (T4-LD8)
    unavailable             503: the service cannot answer right now
    access_unavailable      503: access codes cannot be checked or made right now (the server is not configured for them); nothing was created
    at_capacity             503: today's research capacity is used up; new runs start again after the next UTC midnight (see Retry-After); nothing was charged
    restarting              503: the server is restarting for an update and starts no new run; nothing was charged, try again after Retry-After (a few seconds)
    admin_password_unavailable503: the owner's password sign-in is not configured on this server (no valid password hash or no admin email); nobody was signed in
    google_signin_unavailable503: Google sign-in is not configured on this server; use an access code instead
    search_unavailable      503: the video search provider is refusing our requests right now, so a run would fail; nothing was reserved, try again after Retry-After
    invalid_link            422: the url is not a public Instagram Reel, TikTok video or YouTube Short link starting with https://; nothing was charged
    not_a_short             422: the linked post is a photo, a carousel or a video over 180 seconds, not a short; the credits came back
    review_not_possible     422: too few short videos on the subject could be read to rate the clip against; the credits came back, try a broader subject
    channel_state_invalid   422: the channel connection link is forged, changed or older than 10 minutes; press Connect again
    channel_scopes_missing  422: Google did not grant both read-only permissions; connect again and leave both boxes ticked
    no_youtube_channel      422: the Google account picked has no YouTube channel; connect again and pick the account (or brand account) that owns it
    google_refused          422: Google did not accept the connection (its code was used, is too old or belongs to another try); press Connect again
    channel_wrong_account   403: the channel connection was started by another Hook Detector account; finish it signed in as that account
    channel_state_used      409: this channel connection link was already used; press Connect again
    channel_connected_elsewhere409: this YouTube channel is connected to another Hook Detector account; disconnect it there first
    channel_unavailable     503: connecting a YouTube channel is not configured on this server right now; nothing was stored
    channel_connect_paused  503: connecting a YouTube channel is not offered yet (paused by the owner on 2026-10-26); nothing was stored
    google_unavailable      503: Google did not answer; nothing was stored, try again after Retry-After
    not_in_team             404: this account is in no team; create one (POST /v1/team) or accept an invite
    already_in_team         409: this account is already in a team (as owner or member); leave it first
    team_owner_only         403: only the team's owner may do this
    member_not_found        404: no such member in your team
    invite_not_found        404: no such invite: mistyped, revoked, or the team is gone
    invite_used             409: this invite link was already used; ask the owner for a new one
    invite_expired          410: this invite link is older than 7 days; ask the owner for a new one
    invite_wrong_email      403: the invite was made for another email than the one you are signed in with
    too_many_invites        409: the team holds 50 open invites, the most; revoke one first
    team_full               409: the team has 50 members, the most it may hold
    team_has_members        409: the owner cannot leave, or delete the account, while the team has members; remove them first
    team_busy               409: work paid from the team's pool is still running; try again in a few minutes
    team_not_empty          409: the team still owns shared folders or trackers; leaving would erase them
    team_cap_reached        403: this member's monthly cap on the team's pool is spent, or what is left is under what this call needs; nothing was held
    team_invites_unavailable503: team invites cannot be made or read right now (the server secret is not configured); nothing was stored

    401  missing, invalid or revoked API key; key_expired: the key passed its expiry;
         invalid_exchange_token: a web sign-in token that is unknown, used or expired;
         invalid_admin_password: the owner's password sign-in failed
    402  not enough credits; the message states your balance
    403  insufficient_scope: the key lacks the scope the call needs (detail names it);
         key_credit_limit_reached: the key's credit_limit is spent, nothing reserved;
         access_code_required: a signup with no beta access code;
         invalid_access_code: the code is unknown, used up, expired or revoked;
         admin_required: an admin route called with a key whose account is not the
         owner's
    404  no such run, hook, conversation or active key on this account;
         account_not_found: an admin route named no account
    409  a key limit (10 active keys at most, the last one cannot be revoked),
         a run in flight blocks deleting the account, or a run in flight cannot export
    413  the request body is over 64 KB
    422  invalid input: a bad id, topic length, count, language (over 60
         characters), country (not an assigned ISO 3166-1 alpha-2 code; a region code is
         answered with its country), limit, cursor, label,
         key name, wait, export format or Idempotency-Key, a reused Idempotency-Key with a
         different body, or a missing account deletion confirmation;
         credits_below_zero: an owner's credit change would take a balance below zero
    429  rate limited (signups per address, chat turns and new keys per account, waiting
         requests per account); see Retry-After
    429  too_many_runs: the account already has 2 research runs in flight;
         nothing was reserved, start again when one finishes
    500  our fault; the detail names the request id, nothing is charged
    503  the chat's language model is unavailable; nothing was charged, try again
    503  unavailable: every database connection stayed busy for 30 seconds; nothing was
         charged, retry after Retry-After seconds
    503  at_capacity: today's research capacity (all accounts, UTC day) is used up; nothing
         was reserved, Retry-After counts to the next UTC midnight
    503  search_unavailable: the video search provider is refusing our requests right now,
         so a run would fail; nothing was reserved, retry after Retry-After seconds
    503  google_signin_unavailable: Google sign-in is not configured on this server; sign
         up with an access code instead
    503  access_unavailable: access codes cannot be checked or made right now; nothing was
         created, try again later
    503  admin_password_unavailable: the owner's password sign-in is not configured on this
         server; nobody was signed in
    503  restarting: the server is being updated and starts no new run; nothing was
         reserved, retry after Retry-After seconds (a few) with the same Idempotency-Key

While we deploy, a request can very rarely be answered by our hosting edge instead of the
API: a 502, 503 or 504 whose body is not JSON (an HTML page). It is transient. Retry the
same request with the same Idempotency-Key after a few seconds: a start that did reach us
returns its run, and nothing is reserved twice.

## Rate limits

Access requests (POST /v1/access/requests, 5 per address), failed access codes
(10 per address), signups (POST /v1/accounts, per address; an IPv6 address counts per /64), chat turns
(POST /v1/chat, per account) and new keys (POST /v1/keys, per account) are limited per
hour. Failed owner sign-ins (POST /v1/auth/admin-signin) are limited to
5 per address per 15 minutes and 20 from all
addresses per hour. Their responses, the 429
included, carry:

    X-RateLimit-Limit      requests allowed per hour
    X-RateLimit-Remaining  requests left in the current hour
    X-RateLimit-Reset      seconds until the oldest counted request leaves the hour
    Retry-After            on a 429: seconds to wait before trying again

## MCP

The same operations are tools at https://api.hookdetector.com/mcp over streamable HTTP, one per REST route. Send
the key as the header Authorization: Bearer hd_... or pass it as the api_key argument.

    create_account      POST /v1/accounts  (takes access_code, required for a new account)
    request_access      POST /v1/access/requests
    list_access_requests    GET /v1/admin/requests  (owner only)
    approve_access_request  POST /v1/admin/requests/{request_id}/approve  (owner only)
    reject_access_request   POST /v1/admin/requests/{request_id}/reject  (owner only)
    list_access_codes       GET /v1/admin/codes  (owner only)
    create_access_code      POST /v1/admin/codes  (owner only)
    revoke_access_code      DELETE /v1/admin/codes/{code_id}  (owner only)
    admin_overview          GET /v1/admin/overview  (owner only)
    admin_list_accounts     GET /v1/admin/accounts  (owner only)
    admin_adjust_credits    POST /v1/admin/accounts/{account_id}/credits  (owner only)
    admin_list_runs         GET /v1/admin/runs  (owner only)
    admin_list_actions      GET /v1/admin/actions  (owner only)
    balance             GET /v1/me
    delete_account      DELETE /v1/account
    usage               GET /v1/usage
    list_keys           GET /v1/keys
    create_key          POST /v1/keys
    revoke_key          DELETE /v1/keys/{key_id}
    find_hooks          POST /v1/research
    find_long_hooks     POST /v1/longform  (long-form YouTube outliers: how they open)
    find_packaging      POST /v1/packaging  (their titles and thumbnails, and ideas)
    get_find            GET /v1/finds/{find_id}
    keep_find           POST /v1/finds/{find_id}/decision
    clear_find_decision  DELETE /v1/finds/{find_id}/decision
    list_kept_finds     GET /v1/finds/keeps
    list_finds          GET /v1/finds  (the index: every video found, by outlier score)
    remix_find          POST /v1/finds/{find_id}/remix  (1 credit; mode intro + video_brief is Write my intro)
    list_remixes        GET /v1/hooks/{hook_id}/remixes  (or find_id: GET /v1/finds/{find_id}/remixes)
    get_remix           GET /v1/remixes/{remix_id}
    list_runs           GET /v1/runs
    get_run             GET /v1/runs/{run_id}
    export_run          GET /v1/runs/{run_id}/export
    get_hook            GET /v1/hooks/{hook_id}  (its still_url is GET /v1/hooks/{hook_id}/still)
    embed_hook          GET /v1/hooks/{hook_id}/embed
    keep_hook           POST /v1/hooks/{hook_id}/decision
    clear_decision      DELETE /v1/hooks/{hook_id}/decision
    remix_hook          POST /v1/hooks/{hook_id}/remix  (1 credit)
    list_keeps          GET /v1/keeps
    chat                POST /v1/chat
    list_conversations  GET /v1/conversations
    get_conversation    GET /v1/conversations/{conversation_id}
    showcase            GET /v1/showcase  (no key needed)
    create_folder       POST /v1/folders  (a named folder on one tab: short, long or packaging)
    list_folders        GET /v1/folders  (with hook_id or find_id: which folders hold it)
    get_folder          GET /v1/folders/{folder_id}
    rename_folder       PATCH /v1/folders/{folder_id}
    delete_folder       DELETE /v1/folders/{folder_id}
    save_to_folder      POST /v1/folders/{folder_id}/items  (a hook_id, find_id or video_id, and a note)
    edit_folder_item    PATCH /v1/folders/{folder_id}/items/{item_id}
    remove_from_folder  DELETE /v1/folders/{folder_id}/items/{item_id}
    share_folder        POST /v1/folders/{folder_id}/share  (a public read-only link)
    unshare_folder      DELETE /v1/folders/{folder_id}/share
    get_shared_folder   GET /v1/shared/folders/{token}  (no key needed)
    swipe_file          GET /v1/swipe  (title structures of your kept or filed packages)
    thumbnail_attention  POST /v1/thumbnails/attention  (a predicted attention heatmap on a thumbnail, free)
    create_poll         POST /v1/polls  (2 to 4 packages put to Hook Detector's users, 2 credits)
    list_polls          GET /v1/polls
    get_poll            GET /v1/polls/{poll_id}  (votes, shares, 95% intervals, leader, slots, reasons)
    delete_poll         DELETE /v1/polls/{poll_id}
    next_poll           GET /v1/polls/next  (a poll waiting for your vote, your own order, no counts)
    vote_poll           POST /v1/polls/{poll_id}/vote  (the slot you picked, an optional reason)
    close_poll          POST /v1/polls/{poll_id}/close  (end your poll now, its votes kept)
    video_badges        GET /v1/videos/badges?ids=  (the extension's card badges, free)
    share_run           POST /v1/runs/{run_id}/share  (a public page of a finished Short form run; its data: GET /v1/shared/{token}, no key)
    start_job           POST /v1/jobs  (echo: watch the job runner)
    list_jobs           GET /v1/jobs
    get_job             GET /v1/jobs/{job_id}
    make_thumbnails     POST /v1/thumbnails  (concepts, then images; 4 credits a 1K image)
    get_thumbnails      GET /v1/thumbnails/{call_id}
    edit_thumbnail      POST /v1/thumbnails/edit  (erase, edit, face_swap, text, upscale, fix, crop, color)
    recreate_thumbnail  POST /v1/thumbnails/recreate
    optimize_video      POST /v1/optimize  (new packages for a published video; 10 credits a package)
    get_optimize        GET /v1/optimize/{call_id}
    ab_set              POST /v1/ab  (2 or 3 thumbnails packed for YouTube's Test and Compare; free)
    score_package       POST /v1/packaging/score  (part by part against the outliers; 1 credit)
    preview_package     POST /v1/packaging/preview  (a mock feed with yours in it, as a PNG)
    save_preset         POST /v1/presets  (a named set of filters for a tab; free)
    list_presets        GET /v1/presets
    delete_preset       DELETE /v1/presets/{preset_id}
    write_titles        POST /v1/titles  (20 to 40 titles, each from a real outlier; 1 credit)
    write_ideas         POST /v1/ideas  (ideas: title, thumbnail concept, the finds behind each; 1 credit)
    get_call            GET /v1/calls/{call_id}  (a paid tool's call read back)
    list_calls          GET /v1/calls
    get_skeleton        POST /v1/finds/{find_id}/skeleton  (the whole video mapped, every quote checked; 5 credits)
    review_video        POST /v1/review  (Video Review of your YouTube video; 15 credits)
    read_retention_graph  POST /v1/review/graph  (your YouTube Studio retention graph read; 1 credit)
    review_hook         POST /v1/review/hook  (Hook Review of your opening; 3 credits)
    write_hook          POST /v1/openings  (openings for your video from real outliers; 1 credit)
    write_script        POST /v1/scripts  (a full script from real outlier skeletons; 10 credits)
    review_script       POST /v1/scripts/review  (Script Review; 3 credits)
    review_edit         POST /v1/review/edit  (Edit Review with markers to download; 25 credits)
                        POST /v1/review/edit/upload  (the same, your cut sent as the file itself, up to 500 MB)
    write_upload_pack   POST /v1/seo  (description, chapters and tags; 1 credit)
    clean_recording     POST /v1/clean  (the talking-head cleaner: silences, retakes, fillers, other mics synced; 15 credits)
                        POST /v1/clean/files  (stage each recording first, sent as the file itself, free)
    find_similar        GET /v1/finds/{find_id}/similar  (videos, titles or thumbnails like a find; free)
    search_thumbnails   GET /v1/index/thumbnails  (by what the picture shows; image_url: POST /v1/index/thumbnails/by-image)
    search_index        GET /v1/index/search  (the shared index of outliers, free)
    random_outliers     GET /v1/index/random  (free)
    trending_shorts     GET /v1/shorts/trending  (free: the short videos rising now on a subject)
    review_short        POST /v1/review/short  (3 credits: one Reel, TikTok or Short rated against real finds)
    list_strategies     GET /v1/strategies  (the hook strategy library, counted from the index; free)
    get_channel         GET /v1/channels/{ref}  (every recent upload scored, free)
    channel_outliers    GET /v1/channels/{ref}/outliers  (scope own or niche)
    similar_channels    GET /v1/channels/{ref}/similar
    search_channels     GET /v1/channels/search
    niche_report        GET /v1/niches/{slug}
    list_niches         GET /v1/niches
    list_research       GET /v1/findings  (findings counted from the index, each reproduced on a second sample or not; no key needed)
    get_research        GET /v1/findings/{slug}  (openings, title-devices or title-thumbnail-overlap; no key needed)
    research_keywords   POST /v1/keywords  (estimated volume, competition, a 0 to 100 score in five bands, related terms, questions, rising terms; 2 credits)
    comment_insights    POST /v1/comments/insights  (what a subject's audience asks and struggles with, counted in code, real comments quoted; 3 credits)
    find_sponsors       POST /v1/sponsors  (who sponsors the channels on a subject, from the outliers' descriptions; 1 credit)
    video_stats         GET /v1/videos/{video_id}/stats  (views per hour, free)
    list_winners        GET /v1/winners  (real title and thumbnail changes; pictures at GET /v1/winners/{change_id}/thumb/{side})
    create_tracker      POST /v1/trackers  (1 credit a tracked channel a day)
    list_trackers       GET /v1/trackers
    get_tracker         GET /v1/trackers/{tracker_id}
    update_tracker      PATCH /v1/trackers/{tracker_id}
    delete_tracker      DELETE /v1/trackers/{tracker_id}
    add_to_tracker      POST /v1/trackers/{tracker_id}/channels
    remove_from_tracker  DELETE /v1/trackers/{tracker_id}/channels/{ref}
    tracker_feed        GET /v1/trackers/{tracker_id}/feed
    clone_tracker       POST /v1/trackers/{tracker_id}/clone
    tracker_alerts      GET /v1/trackers/alerts
    create_alert        POST /v1/alerts  (a saved search checked daily or weekly; 1 credit a check)
    list_alerts         GET /v1/alerts
    get_alert           GET /v1/alerts/{alert_id}
    update_alert        PATCH /v1/alerts/{alert_id}
    delete_alert        DELETE /v1/alerts/{alert_id}
    run_alert           POST /v1/alerts/{alert_id}/run
    create_webhook      POST /v1/webhooks  (signed deliveries of tracker alerts and search hits)
    list_webhooks       GET /v1/webhooks
    delete_webhook      DELETE /v1/webhooks/{webhook_id}
    test_webhook        POST /v1/webhooks/{webhook_id}/test
    webhook_deliveries  GET /v1/webhooks/{webhook_id}/deliveries
    video_scorecard     GET /v1/videos/{video_id}/scorecard  (free)
    list_trends         GET /v1/trends  (rising words and phrases, free)
    list_formats        GET /v1/formats  (title formats that win, free)
    format_videos       GET /v1/formats/{format_id}
    get_team            GET /v1/team  (your team: seats, the shared pool, members; usage and invites for the owner; free)
    create_team         POST /v1/team  (a team you own, its pool funded from your balance; free)
    move_team_credits   POST /v1/team/credits  (your balance to the pool, or back; owner; free)
    invite_to_team      POST /v1/team/invites  (a single-use link, emailed to the person and yours to copy, 7 days; free)
    revoke_team_invite  DELETE /v1/team/invites/{invite_id}
    view_team_invite    GET /v1/team/invites/{token}  (what a link joins, before accepting)
    accept_team_invite  POST /v1/team/invites/{token}/accept  (join: the pool pays your spending, your runs stay private)
    remove_team_member  DELETE /v1/team/members/{member_id}  (remove a member, or "me" to leave)
    set_team_member_cap  PATCH /v1/team/members/{member_id}  (a member's monthly cap on the pool; owner)
    daily_ideas         GET /v1/ideas/daily  (daily idea sets; turn on with daily_ideas on an alert or tracker)
    create_agent        POST /v1/agents  (reviews each new upload of a tracker's channels, on a monthly budget)
    list_agents         GET /v1/agents
    get_agent           GET /v1/agents/{agent_id}
    update_agent        PATCH /v1/agents/{agent_id}
    delete_agent        DELETE /v1/agents/{agent_id}

REST only: these routes have no MCP twin of their own (the tool named beside each does the
agent's half), so tools/list holds one tool for every other route:

    GET /v1/hooks/{hook_id}/still                 a JPEG for an <img> tag; on MCP get_hook carries its still_url
    GET /v1/hooks/{hook_id}/media                 a video file for a <video> tag; on MCP get_hook carries its media_url
    GET /v1/runs/{run_id}/thumbs/{key}            a live wall picture for an <img> tag; on MCP its URL is in get_run's progress.feed
    GET /v1/winners/{change_id}/thumb/{side}      a changed thumbnail for an <img> tag; on MCP its URL is in list_winners
    GET /v1/auth/google/start                     the browser's Google sign-in redirect; an agent signs up with create_account and a code
    GET /v1/auth/google/callback                  where Google sends the browser back; an agent signs up with create_account and a code
    POST /v1/auth/exchange                        the web's one-time sign-in token traded for a key; an agent gets its key from create_account
    POST /v1/auth/admin-signin                    the owner's password sign-in in the browser; an agent uses an admin-scoped key
    POST /v1/auth/signout                         the web's sign-out button; on MCP revoke_key revokes any key
    POST /v1/review/edit/upload                   a cut sent as a file; a chat cannot send one, so on MCP review_edit takes the link
    POST /v1/clean/files                          a recording sent as a file; a chat cannot send one, so on MCP clean_recording takes staged file_id values
    GET /v1/shared/{token}                        a shared run's public page, read with no key; on MCP share_run mints it
    GET /v1/public/{kind}                         the public pages' data, read with no key; on MCP list_niches gives the same numbers
    GET /v1/public/{kind}/{slug}                  one public page's data, read with no key; on MCP niche_report gives the same numbers
    POST /v1/free/title                           a free tool with no key and a daily cap; an agent with a key calls score_package
    GET /v1/free/outlier                          a free tool with no key and a daily cap; an agent with a key calls video_scorecard
    GET /v1/free/preview                          a free tool with no key and a daily cap; an agent with a key calls preview_package
    GET /v1/free/thumbnail                        a free tool with no key and a daily cap; an agent with a key calls video_scorecard
    POST /v1/free/hooks                           a free tool with no key and a daily cap; an agent with a key calls find_hooks

find_hooks takes topic, count, conversation_id, reuse, idempotency_key, language, country,
posted_within_days, seed_hook_ids, platforms and wait_seconds (0 to 50); language,
country, posted_within_days, seed_hook_ids and platforms behave as on POST /v1/research, regions and
mixed varieties included. remix_hook takes hook_id, niche and n (1 to 5); remix_find also takes mode and video_brief (Write my intro). Each tool's input schema carries the
bounds and a description per argument (topic 3 to 500 characters, count 1 to
30, wait_seconds 0 to 50, language up to 60 characters,
country two letters). get_run takes run_id and wait_seconds (0 to 50). A fresh
run takes about 2 to 3 minutes (up to about 5 on a dialect request): call get_run with wait_seconds=50 until status is
done or failed. find_hooks with wait_seconds above 0 returns the run object, as get_run
does, plus credits_reserved. usage, list_keys, create_key (name, scopes, credit_limit,
expires_in_days) and revoke_key (key_id, or "others" for every key but yours) return the
same shapes as their REST routes, as do list_runs, list_keeps and
list_conversations (limit and cursor, with next_cursor) and balance (the /v1/me shape).
export_run returns {"filename", "content_type", "format", "content"}, content being the
whole file as text. delete_account takes confirm, exactly "delete my account". An
error is a tool result with isError true whose whole text is JSON, with no prefix:
{"error": {"code": <the REST status>, "message": "...", "error_code": "<the REST body's
code>"}}, plus "retry_after" (seconds) whenever REST would send a Retry-After header. A
422 adds "errors" as on REST, loc being the argument's name (["country"],
["wait_seconds"]); an argument the input schema refuses (count 31) is the same 422. Two
texts are not JSON: an unknown tool name reads "Unknown tool: <name>", and a server crash
reads "Error executing tool <name>". One known difference from REST: MCP checks the
arguments against the input schema before the key, so a call with both a bad argument
and a bad key is 422 over MCP and 401 over REST.

Registry entry (MCP server.json format): https://api.hookdetector.com/server.json, also at
https://api.hookdetector.com/.well-known/mcp.json. For monitoring: https://api.hookdetector.com/health/deep (database round trip, applied
migrations, whether provider keys are configured; 503 when any is missing), commit (the
git commit the running build was made from, also on /health), credits_today ({"day",
"reserved", "ceiling"}: how much of today's research capacity is taken) and its
provider_status: for "model" and "search", state "ok", "refusing" or "unknown", with
last_failure_at, last_success_at and a message when refusing, plus refusing (true when
either is). provider_status.model.primary says whether the main model served recent runs
("ok", "down" with since and a message when the backup answered instead, or "unknown"); a
down main model still answers your runs, at a higher cost to us. It is read from how runs
and chat turns ended in the last 30 minutes and
cached for 30 seconds; it never calls a provider or spends a credit. A refusing provider
does not make /health/deep 503: check it before starting a run, because a run started then
will probably fail (and cost nothing). provider_status.search also carries our own
credits_left with the search provider (read in the background at most every 10 minutes,
never on your request), low (true under low_threshold, about a day of use),
warn_threshold (the owner is told under it), run_minimum (the most one short-form run may
spend with the provider), run_minimums (the same for short, long and packaging),
accepting_runs (false while the provider refuses us, or while credits_left is under the
smallest run_minimums: new runs are then 503 search_unavailable at once, nothing reserved)
and accepting (per kind: false also while credits_left is under that kind's minimum, and
then only that kind is 503). provider_status.youtube_audio says how long-form openings'
audio was reached in the last hour: route (the one that last gave an opening), order,
ok_last_hour, failed_last_hour, routes (each route's counts) and state ("ok", "down" when
every route failed for 10 minutes, or "unknown"); while it is down a long-form run still
delivers its finds, each opening marked "Could not be heard right now" (opening_heard
false) with no words. provider_status.speech is the speech provider's balance (read in
the background at most every 10 minutes): used, limit, left, left_pct, resets_at, and
state "ok", "low" (under 20% left), "out" or "unknown"; while it is out, runs still
deliver, each hook marked as not heard, with no spoken words. fallback_providers says whether the optional anthropic model
fallback is configured; it never makes /health/deep degraded. model is the language model
plan, names only: Claude only, no backup (since 2026-10-26). Every call is asked of
Claude Haiku 5.5 (claude-haiku-5-5) at effort xhigh, with only the next Anthropic key behind it, and
ElevenLabs Scribe v3 alone hears dialect speech ({"primary": "anthropic", "name":
"claude-haiku-5-5", "effort": "xhigh", "backup": null, "speech": "elevenlabs",
"speech_backup": null}).

## Connect your agent

Get a key first (POST https://api.hookdetector.com/v1/accounts with your access_code, above), then use the
block for your client.
Replace hd_YOUR_KEY. The Claude Code and Codex blocks were run against the live server on
2026-09-22. Cursor, Windsurf, VS Code and Claude Desktop use the same header and were not.

Claude Code:
    claude mcp add --transport http hookdetector https://api.hookdetector.com/mcp --header "Authorization: Bearer hd_YOUR_KEY"

Codex CLI (reads the key from an environment variable):
    export HOOKDETECTOR_API_KEY=hd_YOUR_KEY
    codex mcp add hookdetector --url https://api.hookdetector.com/mcp --bearer-token-env-var HOOKDETECTOR_API_KEY

Cursor (~/.cursor/mcp.json) and Windsurf:
    {"mcpServers": {"hookdetector": {"url": "https://api.hookdetector.com/mcp",
      "headers": {"Authorization": "Bearer hd_YOUR_KEY"}}}}

VS Code (.vscode/mcp.json):
    {"servers": {"hookdetector": {"type": "http", "url": "https://api.hookdetector.com/mcp",
      "headers": {"Authorization": "Bearer hd_YOUR_KEY"}}}}

Claude Desktop (claude_desktop_config.json, through mcp-remote):
    {"mcpServers": {"hookdetector": {"command": "npx", "args": ["-y", "mcp-remote",
      "https://api.hookdetector.com/mcp", "--header", "Authorization: Bearer hd_YOUR_KEY"]}}}

A client that cannot send headers (a URL-only connector): add https://api.hookdetector.com/mcp with no
auth, call create_account once with your access_code, and pass the returned key as api_key
on every tool.

## People: sign in with Google

On https://hookdetector.com a person signs in with Google (or enters an access code), so
the account follows them across devices. The first Google sign-in needs a code, or an
approved access request for that email; after that, none. The browser goes to
GET https://api.hookdetector.com/v1/auth/google/start, Google sends it back to /v1/auth/google/callback, and the web
trades a one-time token (60 seconds, single use) at POST /v1/auth/exchange for a key named
"web sign-in" (all scopes, 30 days; at most 3 per account, the oldest revoked first). POST
/v1/auth/signout revokes the key that calls it. GET /v1/me (and MCP balance) then carries
"user" (email, name, avatar_url, is_admin), null for an account with no person behind it.
A code the owner bound to one email redeems only here, through Google with that verified
email. A sign-in that fails lands on https://hookdetector.com/signin?error=<reason>, one
of: access_code_required, invalid_access_code, access_unavailable, account_conflict, email_not_verified, google_denied, google_failed, google_signin_unavailable, invalid_id_token, invalid_state, rate_limited, signin_failed. Agents never need this: they use a code and a key.

## The owner: admin routes

Only the owner may call these: a key with the admin scope whose account belongs to a person
whose email is in the server's HD_ADMIN_EMAILS (403 insufficient_scope without the scope,
403 admin_required for anyone else, 401 with no key). Each has an MCP tool of the same
backend (listed under MCP above). The owner uses them at https://hookdetector.com/admin.

    GET /v1/admin/requests                   access requests (optional status)
    POST /v1/admin/requests/{request_id}/approve   make a one-use code and email it
    POST /v1/admin/requests/{request_id}/reject    reject a pending request
    GET /v1/admin/codes                      every code, never the code itself
    POST /v1/admin/codes                     make a code (shown once)
    DELETE /v1/admin/codes/{code_id}         revoke a code
    GET /v1/admin/overview                   accounts, runs, hooks, credits, access, search
    GET /v1/admin/accounts                   ?q=&limit=&offset= (limit 1 to 200)
    POST /v1/admin/accounts/{account_id}/credits   {"delta", "note"}: add or remove credits
    GET /v1/admin/runs                       ?limit=&status=&account_id=
    GET /v1/admin/actions                    the audit: sign-ins and credit changes

Credits: delta is a whole number from -1000000 to 1000000, not zero;
note (1 to 200 characters) is required. A change that would take a balance
below zero is 422 credits_below_zero and nothing changes; an unknown account is 404
account_not_found. Every change is written to the audit in the same transaction.

The owner signs in on the web with Google (an email in HD_ADMIN_EMAILS needs no access
code) or with the owner's password: POST https://api.hookdetector.com/v1/auth/admin-signin with {"password": "..."}
(no key) answers a web sign-in key, like /v1/auth/exchange. The server holds only
HD_ADMIN_PASSWORD_HASH (scrypt, made by scripts/admin_password_hash.py), never the
password. A wrong password is 401 invalid_admin_password; failed tries are limited to
5 per address per 15 minutes and 20 from all
addresses per hour (429 rate_limited, Retry-After); without a valid hash or an admin email
it is 503 admin_password_unavailable and nobody is signed in.

## Scope

Hooks (POST /v1/research) come from TikTok, Instagram and YouTube Shorts. Long form and
packaging (POST /v1/longform, POST /v1/packaging) read long-form YouTube only, outliers
only, nothing posted before 2023.

For hooks, clips are ranked above a 50,000 view floor first; when a topic
has fewer than you asked for above it, the rest are the highest below it, each marked with
above_floor false.

Any language or dialect, from any country: set language and country (for example
"Moroccan Darija" and MA, or "Brazilian Portuguese" and BR) or say it in the topic. A
narrow dialect can have less supply than English, so a run may deliver fewer hooks than
asked rather than fill with another language or a neighbouring subject. TikTok honours the country; Instagram does
not report one, so there only the language is checked. A region is its country plus the
regional variety as language (Quebec: CA and "Quebec French").