HookOut

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hookdetector-com/json-schema/hookdetector-com-hook-out-schema.json",
  "title": "HookOut",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hookdetector-com-openapi.json#/components/schemas/HookOut",
  "properties": {
    "hook_id": {
      "type": "string",
      "title": "Hook Id"
    },
    "rank": {
      "type": "integer",
      "title": "Rank"
    },
    "hook": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Hook",
      "description": "the exact opening line; null when the clip had none"
    },
    "catchy_line": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Catchy Line"
    },
    "main_idea": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Main Idea"
    },
    "why_it_travelled": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Why It Travelled"
    },
    "topic": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Topic"
    },
    "onscreen_text": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Onscreen Text",
      "description": "text burned into the video; on hooks found before 2026-09-26, every slide of a photo post in order"
    },
    "transcript": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Transcript"
    },
    "transcript_kind": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "speech",
            "music",
            "none",
            "other"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Transcript Kind"
    },
    "heard": {
      "type": "boolean",
      "title": "Heard",
      "description": "false when our speech service could not hear the clip right now: it shows no spoken words and transcript is null; true otherwise",
      "default": true
    },
    "language": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Language",
      "description": "the language or dialect the clip was judged to be in, named in English (\"Moroccan Darija\", not \"Arabic\"); null for hooks found before this field"
    },
    "platform": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "tiktok",
            "instagram",
            "youtube"
          ]
        },
        {
          "type": "string"
        }
      ],
      "title": "Platform",
      "description": "tiktok, instagram or youtube (YouTube Shorts only, never long-form, since 2026-10-01; its watch_url is the Shorts form)"
    },
    "creator": {
      "type": "string",
      "title": "Creator"
    },
    "views": {
      "type": "integer",
      "title": "Views"
    },
    "likes": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Likes"
    },
    "above_floor": {
      "type": "boolean",
      "title": "Above Floor"
    },
    "watch_url": {
      "type": "string",
      "title": "Watch Url"
    },
    "cover_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Cover Url"
    },
    "slide_count": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Slide Count",
      "description": "always null on hooks found since 2026-09-26 (no carousels are delivered); the slide count of a TikTok photo post on older hooks"
    },
    "found_by": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Found By"
    },
    "caption": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Caption"
    },
    "verdict": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Verdict"
    },
    "format": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Format",
      "description": "what kind of clip it is: talking_head, podcast, interview, stage (a person on camera talking; the main deck), 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 talking to the viewer), other (never delivered since 2026-10-08). Null on hooks found before 2026-09-29. A client should treat an unknown value as other."
    },
    "section": {
      "type": "string",
      "const": "main",
      "title": "Section",
      "description": "always \"main\": the deck of a person on camera talking. Bonus was removed on 2026-10-08, and bonus hooks older runs stored are no longer returned.",
      "default": "main"
    },
    "creator_country": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Creator Country",
      "description": "the country of the creator's TikTok account as an ISO 3166-1 alpha-2 code (\"MA\"), as TikTok states it on the clip's search row. It is the account's country, not GPS. Always null on Instagram, which states none, and on hooks found before 2026-09-30. Never guessed."
    },
    "place": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Place",
      "description": "the name of the place the creator tagged on the post (at most 80 characters), null when untagged, as most posts are. Where it was posted from, not where the creator lives."
    },
    "place_country": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Place Country",
      "description": "the tagged place's country as an ISO 3166-1 alpha-2 code, only when the platform states it (TikTok usually does, Instagram rarely). Null otherwise; never guessed from the name or the map position."
    },
    "banner": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Banner",
      "description": "since 2026-09-30: 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 as 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."
    },
    "match": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "exact",
            "close"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Match",
      "description": "since 2026-09-30, on runs 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 (general wealth-building advice for \"getting wealthy in your 20s\"): a close match, delivered after every exact match and to be labelled as one. Null on hooks found before 2026-09-30 and on runs with no language or country, which are judged as before."
    },
    "style_match": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Style Match",
      "description": "since 2026-10-04, on a run whose request asked for a kind of opening (\"controversial hooks\", \"question hooks\", \"storytime\"): true when this hook opens that way (its hook_type is one asked), false when it is a strong hook on the subject that opens differently, delivered after the ones that match. Null when no kind was asked."
    },
    "signals": {
      "properties": {
        "followers": {
          "type": "integer",
          "description": "the creator's followers"
        },
        "shares": {
          "type": "integer"
        },
        "saves": {
          "type": "integer"
        },
        "comments": {
          "type": "integer"
        },
        "posted": {
          "type": "string",
          "description": "the post date, YYYY-MM-DD, UTC"
        },
        "reach": {
          "type": "number",
          "description": "views over the creator's followers: 12.5 means it reached 12.5 times the creator's own audience"
        },
        "shares_per_1k": {
          "type": "number",
          "description": "shares per 1,000 views"
        },
        "saves_per_1k": {
          "type": "number",
          "description": "saves per 1,000 views"
        },
        "opening": {
          "type": "string",
          "enum": [
            "banger",
            "ok",
            "weak",
            "other"
          ],
          "description": "how hard the clip's first words stop a scrolling viewer, as the write-up rated them; absent on hooks found before 2026-10-13"
        },
        "opening_why": {
          "type": "string",
          "description": "at most 15 words on why the opening rates as it does"
        }
      },
      "type": [
        "object",
        "null"
      ],
      "title": "Signals",
      "description": "how far the clip travelled beyond its creator, from the platform's own numbers (TikTok carries all of them, Instagram at most comments and the post date); each key only when the platform stated it; null for a hook with none. Hooks are ranked by views, reach and shares and saves per view together since 2026-09-28"
    },
    "posted_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Posted At",
      "description": "when the clip was posted, exact when the platform gives it; null when unknown"
    },
    "age_days": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Age Days",
      "description": "days since posted_at, at delivery"
    },
    "views_per_day": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Views Per Day",
      "description": "views divided by age_days"
    },
    "creator_median_views": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Creator Median Views",
      "description": "the creator's usual views per video: the median of their recent videos, pinned excluded (TikTok may use likes per video as a proxy, said so in outlier_basis)"
    },
    "outlier": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Outlier",
      "description": "views divided by the creator's usual views per video (`creator_median_views`): 31.2 means 31 times what this creator normally gets. Null when the creator's baseline was not priced for this run."
    },
    "outlier_basis": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "median_views",
            "likes_per_video"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Outlier Basis",
      "description": "what creator_median_views was measured from, or null"
    },
    "duration_s": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Duration S",
      "description": "the clip's length in seconds"
    },
    "paid": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Paid",
      "description": "an ad, a paid partnership or branded content, as the platform labels it; null when unknown"
    },
    "sound_reuse": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sound Reuse",
      "description": "videos reusing the clip's sound"
    },
    "own_sound": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Own Sound",
      "description": "the sound is the creator's own"
    },
    "hashtags": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Hashtags",
      "description": "the post's hashtags, at most 20, without the #"
    },
    "virality": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Virality",
      "description": "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: the same clip scores the same in every run. Built from the outlier (views over the creator's usual, when known), freshness, travel (shares and saves per 1,000 views), own-sound reuse and a paid penalty; null on hooks found before this field."
    },
    "virality_why": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Virality Why",
      "description": "one short line naming the strongest signal behind `virality` (\"31x this creator's usual\", \"1.2M views in 4 days\"); never empty when virality is set; null when unknown"
    },
    "hook_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Hook Type",
      "description": "since 2026-10-02: the device the opening uses, one of curiosity_gap, contrarian_claim, specific_number, identity_callout, stakes_threat, promise_payoff, pattern_interrupt, story_open, question, direct_command, other (then `hook_type_other` names it in two to five words). Null on older hooks and when the write-up gave none. A client should treat an unknown value as other."
    },
    "hook_type_other": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Hook Type Other",
      "description": "two to five words naming the device when hook_type is other, else null"
    },
    "mechanism": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Mechanism",
      "description": "since 2026-10-02: why the opening stops the scroll, in at most two short sentences: what the first three seconds make the viewer think or feel, quoting the clip's own words (every quote is checked word for word against what was said or shown), and the open question the clip then pays off. Never a view or follower count. `why_it_travelled` carries the same text. Null on older hooks."
    },
    "visual_hook": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Visual Hook",
      "description": "since 2026-10-02: one sentence on what the banner or other on-screen text adds to the spoken opening; null when no on-screen text hooks"
    },
    "audience": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Audience",
      "description": "since 2026-10-02: the specific viewer this opening stops, a few words"
    },
    "template": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Template",
      "description": "since 2026-10-02: the hook as a fill-in structure of at most 20 words, its subject words replaced by {placeholders}"
    },
    "steal_it": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Steal It",
      "description": "since 2026-10-02: one sentence on how a creator in another niche reuses this exact move"
    },
    "video_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Video Id"
    },
    "player_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Player Url",
      "description": "a 9:16 iframe src (TikTok's player, Instagram's reel embed, YouTube's embed); null for an unusable id or a photo post found before 2026-09-26"
    },
    "aspect": {
      "type": "string",
      "title": "Aspect"
    },
    "still_url": {
      "type": "string",
      "title": "Still Url",
      "description": "the card image as a JPEG, served by this API; no key needed"
    },
    "media_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Media Url",
      "description": "our own player's source: put it in a <video src>; it redirects to the clip's original file on TikTok's or Instagram's CDN (no key, nothing stored). null for YouTube (use player_url) and photo posts; a 404 or 503 from it means show player_url instead"
    }
  },
  "additionalProperties": true,
  "type": "object",
  "required": [
    "hook_id",
    "rank",
    "hook",
    "catchy_line",
    "main_idea",
    "why_it_travelled",
    "topic",
    "onscreen_text",
    "transcript",
    "platform",
    "creator",
    "views",
    "likes",
    "above_floor",
    "watch_url",
    "cover_url",
    "slide_count",
    "found_by",
    "caption",
    "verdict",
    "video_id",
    "player_url",
    "aspect",
    "still_url"
  ]
}