packaging

Find packaging: the titles and thumbnails that earned the click on a topic.

Start a packaging run and return its run_id at once. It finds the long-form YouTube videos on the topic that beat their own channel (the same outlier search as POST /v1/longform, 2023 or later), looks at each one's thumbnail beside its title, and returns the pairs as the run's finds: title and thumbnail_url (YouTube's own), views and outlier, and what the package does: title_device, title_template, thumbnail_text, thumbnail_subject, thumbnail_composition, thumbnail_devices and gap (what the picture shows that the title does not say). report then holds title_patterns and thumbnail_patterns (what at least two of them share) and ideas: up to ideas (6 by default) titles and thumbnail concepts written for your topic from those patterns, always labelled as written, never counted as a find, and numbers: the packages counted (title length, how many carry a number or a question, how many thumbnails print words, which devices repeat). GET /v1/runs/{run_id}?wait=55 until done; while it runs, progress.items holds the packages looked at so far, as cards, and progress.scan the videos it is looking at. It reserves up to 70 credits for 24 packages or fewer and 3 more for each package above that (88 for the largest count, 30; down to 25) and charges only the provider calls it made (the searches, one call per channel measured, and one for each video whose date had to be read exactly): looking at a thumbnail costs none. A failed run costs nothing, and so does one that finds nothing, inside the allowance. How long it takes has not been measured yet: poll, never assume a time. topic may be a channel's or a video's YouTube address, and channel_size narrows to channels of one size, exactly as on POST /v1/longform; no ideas are written for a link. Starts are limited per account per hour (429). Needs research. MCP: find_packaging.

post/v1/packaging

Request

  • Base URL: https://api.hookdetector.com (the document declares no server; this is the origin it was published from)
  • URL: https://api.hookdetector.com/v1/packaging
  • Auth: none declared

Headers

Idempotency-Keystring nullable

retry safely: the same key within 24 hours returns the first run and reserves nothing

authorizationstring nullable

Bearer hd_... from POST /v1/accounts or POST /v1/keys

Request body

topicstring required

the subject to research, 3 to 500 characters, in any language. Or a YouTube address instead of a subject: a channel's (https://www.youtube.com/@name, or just @name) returns that channel's own outliers, its recent long-form uploads that beat its usual; a long-form video's (https://www.youtube.com/watch?v=...) returns that one video, whatever its multiple. A Short's address is refused (422)

countinteger

how many packages to deliver, 1 to 30

languagestring nullable

optional, up to 60 characters: the language the videos should be spoken in, in words or as a tag ("Spanish", "pt-BR"). Left out, it is read from the topic's own language

countrystring nullable

optional, an assigned ISO 3166-1 alpha-2 code (US, GB, MA): searches YouTube as seen from this country. It steers the search; it does not filter the channels

min_outliernumber nullable

optional, 1.5 to 100 (default 2): how many times its own channel's usual views a video must have to count as an outlier. Only outliers are ever delivered

posted_within_days30 | 90 | 365 | 730 | null nullable

optional, how recent the videos must be, as days: 30, 90, 365, 730. Null or left out means everything since 2023-01-01; nothing older is ever delivered

channel_size'small' | 'medium' | 'large' | 'null' nullable

optional: only videos from channels of this size, by what the channel's uploads usually get (its median views, the figure the outlier is measured against): small (under 20,000), medium (up to 200,000) or large. Null or left out: any size

ideasinteger nullable

optional, 0 to 10 (default 6): how many written packages (a title and a thumbnail concept) to add for the subject; 0 for none

reuseboolean

start from the videos your last long or packaging run on this topic already bought (within a week), so the second tab on a topic costs little

Example request

{
  "topic": "home espresso",
  "language": "Spanish",
  "country": "US",
  "min_outlier": 3,
  "posted_within_days": 365,
  "channel_size": "small",
  "ideas": 6
}

Response

a replay of an earlier start with the same Idempotency-Key; nothing was reserved

run_idstring required
statusstring required
kindstring

what the run researches: "short" (hooks from TikTok, Instagram and YouTube Shorts, POST /v1/research), "long" (how long-form YouTube outliers open, POST /v1/longform) or "packaging" (their titles and thumbnails, POST /v1/packaging). Every run from before 2026-10-07 is short

topicstring required
requestedinteger required
languagestring nullable

the language or dialect asked for, as sent, or null for any language

countrystring nullable

the country asked for, as an ISO 3166-1 alpha-2 code (upper-cased, UK read as GB), or null for any country

posted_within_daysinteger nullable

the recency window asked for (7, 30, 90 or 365 days), or null

seed_hook_idsstring[] nullable

the seed hooks asked for ("find more like these"), or null

platformsstring[] nullable

the platforms this Short form run searches and delivers from ("tiktok", "instagram", "youtube"): the ones asked for, or all three; null on a long or packaging run

credits_reservedinteger required
created_atstring required

Example response

{
  "created_at": "2026-09-23T10:00:00.000000+00:00",
  "credits_reserved": 200,
  "requested": 10,
  "run_id": "8f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f",
  "status": "queued",
  "topic": "cold plunge recovery"
}

Changes

No recorded changes to this operation across all 1 revision of this API.