Awzor Media LLC Public API

openapi: 3.2.0
info:
  title: Hook Detector Public API
  description: 'Find short-form hooks that already work.


    Sign up with a beta access code (ask at https://hookdetector.com/access): one POST to

    `/v1/accounts` with `access_code` gives an API key and free credits. The same operations are available as MCP tools at `/mcp`.


    Full guide, always current, at `/llms.txt`.'
  contact:
    name: Hook Detector
    url: https://hookdetector.com/
    email: contact@hookdetector.com
  version: 3.0.0
tags:
- name: Public
paths:
  /v1/public/{kind}:
    get:
      tags:
      - Public
      summary: The public pages of one kind, no key
      description: 'Every listed public page of a kind: `niches` (a niche report with its outlier rate at 10x,

        median views and top outliers), `creators` (a channel''s outliers and the openings read from

        them) or `teardowns` (a Video Review of a popular outlier). Each with its headline numbers,

        from the snapshot the nightly job built from the shared index of public YouTube data. Thin

        pages are never listed. No key needed; limited per address. Free.'
      operationId: public_pages_v1_public__kind__get
      parameters:
      - name: kind
        in: path
        required: true
        schema:
          type: string
          title: Kind
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicListOut'
        '404':
          description: not found on this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '422':
          description: invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '429':
          description: rate limited; see Retry-After
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '500':
          description: our fault; names the request id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
  /v1/public/{kind}/{slug}:
    get:
      tags:
      - Public
      summary: One public page's data, no key
      description: 'One public page as hookdetector.com draws it: a niche (`niches/sourdough`), a creator by

        handle (`creators/veritasium`) or a teardown by video id (`teardowns/dQw4w9WgXcQ`). Every

        number is from a real row of the shared index, counted when the page was built (`built_at`;

        `stale` after 48 hours) and said in `computed_from`. 404 page_not_found for a slug with no

        page; 422 naming kind or slug for one of the wrong shape. No key needed. Free.'
      operationId: public_page_v1_public__kind___slug__get
      parameters:
      - name: kind
        in: path
        required: true
        schema:
          type: string
          title: Kind
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPageOut'
        '404':
          description: not found on this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '422':
          description: invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '429':
          description: rate limited; see Retry-After
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '500':
          description: our fault; names the request id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
  /v1/findings:
    get:
      tags:
      - Public
      summary: The research findings, no key
      description: 'Every research page counted from the shared index of public YouTube data: `openings` (which

        openings sit before a steeper or flatter first minute of YouTube''s "most replayed" heatmap),

        `title-devices` (which title devices go with higher multiples, by niche) and

        `title-thumbnail-overlap` (title and thumbnail word overlap against the multiple). Each is counted

        twice, on two samples split by channel; the counts say how many claims reproduced. No key needed;

        limited per address. Free.'
      operationId: research_pages_v1_findings_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResearchListOut'
        '429':
          description: rate limited; see Retry-After
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '500':
          description: our fault; names the request id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
  /v1/findings/{slug}:
    get:
      tags:
      - Public
      summary: One research page's data, no key
      description: 'One research page as hookdetector.com draws it (`openings`, `title-devices`,

        `title-thumbnail-overlap`): both runs'' numbers for every claim, n per run and per cell, whether it

        reproduced, and `measures` naming what each number is computed from. Built by the daily job

        (`built_at`; `stale` after 48 hours). 404 page_not_found for a slug with no page; 422 naming slug

        for one of the wrong shape. No key needed. Free.'
      operationId: research_page_v1_findings__slug__get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResearchPageOut'
        '404':
          description: not found on this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '422':
          description: invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '429':
          description: rate limited; see Retry-After
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '500':
          description: our fault; names the request id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
components:
  schemas:
    PublicPageOut:
      properties:
        kind:
          type: string
          title: Kind
        slug:
          type: string
          title: Slug
        title:
          type: string
          title: Title
        listed:
          type: boolean
          title: Listed
          description: 'false for a page under its kind''s bars: served, but never listed, and the web marks it noindex'
        stale:
          type: boolean
          title: Stale
          description: true when the page was built more than 48 hours ago
        built_at:
          type: string
          title: Built At
        rows:
          type: integer
          title: Rows
          description: the real rows the page is counted from
        computed_from:
          anyOf:
          - type: string
          - type: 'null'
          title: Computed From
          description: what every number on the page is counted from, and when
        data:
          additionalProperties: true
          type: object
          title: Data
        credits:
          type: integer
          title: Credits
          default: 0
      additionalProperties: true
      type: object
      required:
      - kind
      - slug
      - title
      - listed
      - stale
      - built_at
      - rows
      - data
      title: PublicPageOut
      examples:
      - built_at: '2026-10-27T00:01:00+00:00'
        computed_from: 427 videos in Hook Detector's index ...
        credits: 0
        data:
          median_views: 18250
          videos: 427
        kind: niches
        listed: true
        rows: 427
        slug: sourdough
        stale: false
        title: sourdough
    ErrorOut:
      properties:
        detail:
          type: string
          title: Detail
          description: one sentence a person can read
        code:
          type: string
          title: Code
          description: stable machine code; see the Errors section of /llms.txt
        errors:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Errors
          description: 'on a 422 only: the field level list'
      additionalProperties: true
      type: object
      required:
      - detail
      - code
      title: ErrorOut
      examples:
      - code: run_not_found
        detail: no such run for this account
    PublicListOut:
      properties:
        kind:
          type: string
          title: Kind
          description: niches, creators or teardowns
        pages:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Pages
          description: every listed page of the kind, with its headline numbers; a thin page is never listed
        count:
          type: integer
          title: Count
        built_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Built At
          description: when the newest of these pages was built
        credits:
          type: integer
          title: Credits
          default: 0
      additionalProperties: true
      type: object
      required:
      - kind
      - pages
      - count
      title: PublicListOut
      examples:
      - built_at: '2026-10-27T00:01:00+00:00'
        count: 1
        credits: 0
        kind: niches
        pages:
        - built_at: '2026-10-27T00:01:00+00:00'
          rows: 427
          slug: sourdough
          stale: false
          summary:
            median_views: 18250
            month: '2026-10-01'
            outlier_rate_10x: 0.51
            p75_multiple: 21.4
            videos: 427
          title: sourdough
    ResearchListOut:
      properties:
        pages:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Pages
          description: 'every research page with its counts: n per run, and how many claims reproduced, did not, or had too few videos'
        count:
          type: integer
          title: Count
        built_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Built At
          description: when the newest of these pages was built
        credits:
          type: integer
          title: Credits
          default: 0
      additionalProperties: true
      type: object
      required:
      - pages
      - count
      title: ResearchListOut
      examples:
      - built_at: '2026-10-27T06:00:00+00:00'
        count: 1
        credits: 0
        pages:
        - built_at: '2026-10-27T06:00:00+00:00'
          claims: 533
          n: 8214
          not_reproduced: 40
          question: Which title devices go with higher or lower multiples, and in which niche?
          reproduced: 21
          runs:
            a:
              channels: 1630
              n: 4102
            b:
              channels: 1622
              n: 4112
          slug: title-devices
          stale: false
          title: Title devices that go with higher multiples, by niche
          too_few: 472
    ResearchPageOut:
      properties:
        slug:
          type: string
          title: Slug
        title:
          type: string
          title: Title
        stale:
          type: boolean
          title: Stale
          description: true when the page was built more than 48 hours ago
        built_at:
          type: string
          title: Built At
        n:
          type: integer
          title: N
          description: 'the videos counted: the first run''s plus the second run''s'
        data:
          additionalProperties: true
          type: object
          title: Data
          description: question, measures (what every number is computed from), note, runs (n and channels per run), claims (each run's numbers, shown_a, shown_b, reproduced true, false or null for too few, direction)
        credits:
          type: integer
          title: Credits
          default: 0
      additionalProperties: true
      type: object
      required:
      - slug
      - title
      - stale
      - built_at
      - n
      - data
      title: ResearchPageOut
      examples:
      - built_at: '2026-10-27T06:00:00+00:00'
        credits: 0
        data:
          claims:
          - direction: steeper
            key: hook_type:question
            reproduced: true
          runs:
            a:
              channels: 301
              n: 455
            b:
              channels: 298
              n: 457
        n: 912
        slug: openings
        stale: false
        title: Openings before a steeper or flatter first minute