chat
One conversational turn, for an agent relaying a person's words. It either asks ONE clarifying question (action "clarify"), answers about delivered hooks or the tool (action "answer", run null, no credits), or starts a research run (action "research", with the started run under "run"), exactly like POST /v1/chat. Every response has suggestions: 0 to 4 follow-ups, [] for 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 count argument
sets the deck size when the message states none. 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 remix_hook) and answers them
labelled, the full result under "remix".
language and country select the search locale: omitted or null keeps the current
conversation setting; a value sets it for this and later turns; an empty string
clears it to any language / any country. The picker wins over the message's locale;
replies stay in the language the person writes in. Invalid locale: 422 invalid_request.
message is 1 to 4000 characters. Pass conversation_id from an earlier turn to keep
the context; leave it out to start a conversation. Cost: a turn itself is free but is
a model call, so turns are limited per account per hour (429 rate_limited); a turn
that starts a run reserves credits like find_hooks. Next step: on "research", call
get_run with run.run_id and wait_seconds=50. Errors: 503 model_unavailable when the
model is down (nothing charged, try again), 402 insufficient_credits. For direct
research without the question step, call find_hooks instead. Needs the write
permission, and research for a turn that starts a run (403 insufficient_scope, nothing
reserved).Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | 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 | |
| api_key | No | ||
| country | No | 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. | |
| message | Yes | ||
| language | No | 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. | |
| platforms | No | 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`. | |
| seed_hook_ids | No | 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. | |
| conversation_id | No | ||
| idempotency_key | No | retry safely: a turn that started a run with this key within 24 hours answers that run again, no model call, nothing reserved | |
| posted_within_days | No | 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. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |