GET/v1/hooks/searchceil(rows / 25) credits

Search hooks

Lean hook page matching q in the hook text. q is required. Page size is 50. Pass next_cursor back as cursor.

The request reserves 2 credits, then settles ceil(rows / 25). An empty page settles 0. A wallet with 1 credit still gets 402 on reserve.

Needs hooks:read on the key. This is a permission on the key, not a request header. Missing it returns 403 api_not_enabled.

Request parameters

Name	In	Type	Required	Description
`q`	query	string	Required	Search text. Empty or missing is `422 validation_error`.
`cursor`	query	string	Optional	Opaque cursor from the previous page.

Response

{
  "object": "list",
  "data": [
    {
  "id": "hook_9f2a1c0b4e7d4a1f8c3e2d1b0a9f8e7d",
  "text": "Stop scrolling if you edit short-form.",
  "platform": "tiktok",
  "media_type": "video",
  "thumbnail_url": "https://cdn.example/thumb.jpg",
  "category": "education",
  "hook_duration_sec": 2.4,
  "published_at": "2026-03-12T18:04:00.000Z"
}
  ],
  "has_more": true,
  "next_cursor": "cur_01J…"
}

Response fields

Name	Type	Required	Description
`object`	string	Required	Always `list`.
`data`	array	Required	Page of lean hooks. May be empty.
`has_more`	boolean	Required	True when another page exists.
`next_cursor`	string	Nullable	Pass back as `cursor`. `null` when `has_more` is false.

data[] fields

Name	Type	Required	Description
`id`	string	Required	Public id, `hook_` plus 32 hex characters.
`text`	string	Required	Hook copy.
`platform`	string	Required	Source platform, for example `tiktok`.
`media_type`	string	Nullable	Media kind when known.
`thumbnail_url`	string	Nullable	Thumbnail URL when known.
`category`	string	Nullable	Category slug when known.
`hook_duration_sec`	number	Nullable	Opening duration in seconds when known.
`published_at`	string	Nullable	Publish timestamp when known.