chat

One conversational turn. The chat surface uses this.

One turn: an answer about hooks or the tool (action "answer", no credits), one clarifying question (action "clarify"), or a started run (action "research", with the run in run, reserving credits like POST /v1/research). A deck size typed into the message ("..., 15 hooks") and a recency phrase ("this month", "last week") set the run's count and posted_within_days; the body's posted_within_days (the recency chip) wins over the phrase and is kept on the conversation for later turns (an explicit null clears it); seed_hook_ids applies to this turn's research ("find more like these"); count sets how many hooks a run this turn starts delivers (a size typed into the message wins). Asked to make one of the conversation's hooks yours for a niche ("make hook 2 mine for dentists"), the turn writes lines from that hook's structure (1 credit, like POST /v1/hooks/{hook_id}/remix) and answers with them labelled, the result in remix. Every response includes suggestions (0 to 4 follow-ups, [] for research). Each turn is a model call, so turns are limited per account per hour. 503 model_unavailable when the model is down; nothing is charged then. Needs write, and research for a turn that starts a run (403 insufficient_scope before anything is reserved). MCP: chat.

post/v1/chat

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/chat
  • Auth: none declared

Headers

Idempotency-Keystring nullable

retry safely: the same key and body within 24 hours answer the first turn again (its conversation, its answer, its run or its remix): no model call, no new message, nothing charged. The same key with another body is 422 idempotency_key_reused

authorizationstring nullable

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

Request body

messagestring required
conversation_idstring nullable
languagestring nullable

optional, up to 60 characters: only clips spoken or written in this language or dialect, in words or as a tag: "Moroccan Darija", "ar-MA", "Egyptian Arabic", "Brazilian Portuguese". Any language works, including a regional variety ("Quebec French", "Flemish", "Catalan") and a mixed, code-switched one ("Hinglish", "Taglish", "Moroccan Darija with French"), or two joined by "or" ("Tagalog or Taglish"). The value is handed to the judges exactly as written; how well they honour a mixed or either-of value is not measured yet. Saying it inside topic works too; this field wins when both are given. For chat, omitted or null keeps the conversation's current setting; a value sets it for this and later turns; the empty string clears it back to any language / any country.

countrystring nullable

optional: only clips from creators in this country, as an assigned ISO 3166-1 alpha-2 code: MA, EG, BR, US (UK is read as GB). For a region that is not a country, send its country's code and name the regional variety in language: Quebec is country CA with language "Quebec French", Flanders BE with "Flemish", Catalonia ES with "Catalan". The country places the TikTok search there; the language judge does the regional filtering, and Instagram reports no country. A country alone does not restrict the language. For chat, omitted or null keeps the conversation's current setting; a value sets it for this and later turns; the empty string clears it back to any language / any country.

posted_within_days7 | 30 | 90 | 365 | 0 | null nullable

since 2026-10-01: optional, how recent the clips must be, as days: 7, 30, 90, 365. The search asks the platforms for that window and the floor for a clip under 7 days old uses views per day (10,000 a day passes); null or left out means any time. A clip's posted_at and age_days say what the run found. For chat (the recency chip): omitted keeps the conversation's current setting; 7, 30, 90 or 365 sets it for this and later turns and wins over a recency phrase in the message; an explicit null on REST, or 0 on either door, clears it back to any time.

seed_hook_idsstring[] nullable

since 2026-10-01: optional, up to 10 hook ids from your runs (a kept hook from GET /v1/keeps, or any hook you can read): "find more like these". The engine reads their lines, topics, creators and languages to steer the search phrases and the creators it expands; a seed is never delivered again. An id that is not one of your hooks is 422.

countinteger nullable

how many hooks a run this turn starts should deliver, 1 to 30; a size typed into the message ("15 hooks") wins over it, and it wins over the turn's own guess; null or omitted lets the turn decide. Fewer hooks is a faster, cheaper run

platformsstring[] nullable

since 2026-10-10: optional, 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. Names are read without regard to case and a repeat counts once; an empty list or any other name is 422 naming platforms. The run echoes it as platforms.

Example request

{
  "message": "hooks about cold plunge recovery",
  "language": "Moroccan Darija",
  "country": "MA",
  "platforms": [
    "instagram"
  ]
}

Response

Successful Response

conversation_idstring required
action'clarify' | 'research' | 'answer' required
messagestring required
suggestionsstring[] required

Example response

{
  "action": "research",
  "conversation_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "message": "Researching cold plunge recovery.",
  "run": {
    "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"
  },
  "suggestions": []
}

Changes

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