{"openapi":"3.1.0","info":{"title":"Hook Detector","description":"Find short-form hooks that already work.\n\nSign up with a beta access code (ask at https://hookdetector.com/access): one POST to\n`/v1/accounts` with `access_code` gives an API key and free credits. The same operations are available as MCP tools at `/mcp`.\n\nFull guide, always current, at [`/llms.txt`](/llms.txt).\n","contact":{"name":"Hook Detector","url":"https://hookdetector.com/","email":"contact@hookdetector.com"},"version":"2.4.0"},"paths":{"/v1/accounts":{"post":{"tags":["accounts"],"summary":"Sign up with a beta access code. No auth, no form, no human step.","description":"Create an account and get an API key with free credits. Needs a beta access code as\n`access_code` (403 access_code_required without one, 403 invalid_access_code for one\nthat does not work; ask at hookdetector.com/access). The key in this response\nis the only copy that will ever exist: store it, then send it as\n`Authorization: Bearer hd_...` on every other call. Signups are limited per address per\nhour (an IPv6 caller per /64), and so are wrong codes; the X-RateLimit headers say\nwhere you stand. Free. MCP: create_account.","operationId":"signup_v1_accounts_post","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SignupIn"},{"type":"null"}],"title":"Body"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupOut"}}}},"413":{"description":"request body over the size cap","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"}}}},"403":{"description":"no access code (access_code_required), or one that does not work (invalid_access_code): mistyped, used up, expired or revoked, one answer for all","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}}}}},"/v1/me":{"get":{"tags":["accounts"],"summary":"Who am I, what is my balance, what may this key do","description":"The account behind the key: account_id, credits (the balance right now),\nkey_prefix and key_id of the key making this call, label and created_at, and that\nkey's scopes, credit_limit and expires_at (null: no cap, never expires), and `user`:\nthe person signed in with Google who uses the account (null for a key-only account).\nNeeds read. Free. MCP: balance.","operationId":"me_v1_me_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeOut"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input","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/account":{"delete":{"tags":["accounts"],"summary":"Erase your account and everything in it","description":"Erase the account and every row it owns: all its API keys, runs, hooks, keep or\nreject decisions, conversations and messages. It cannot be undone. The body must be\nexactly `{\"confirm\": \"delete my account\"}` (422 confirmation_required otherwise), and\nit is refused with 409 run_in_flight while a run is still queued or running. Any\nunspent credits go with the account. Every key stops working at once. Needs admin.\nMCP: delete_account.","operationId":"delete_account_v1_account_delete","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/DeleteAccountIn"},{"type":"null"}],"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountDeletedOut"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"409":{"description":"conflict with the account's state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input","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/usage":{"get":{"tags":["accounts"],"summary":"Credits, spend, what in-flight runs hold, and the last 30 days","description":"credits (the balance now), spent_total (charged by finished runs), reserved_now\n(held by runs still in flight), runs_total, last_30_days (one entry per UTC day,\noldest first) and recent (the 20 newest runs). credits + spent_total + reserved_now is\neverything the account was given. Needs read. Free. MCP: usage.","operationId":"usage_v1_usage_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageOut"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input","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/keys":{"get":{"tags":["keys"],"summary":"Your API keys and what each may do. Never the keys themselves.","description":"Every key not revoked: in keys, key_id, name, prefix, created_at, last_used_at\n(updated at most every 5 minutes) and current (true for the key making this call); in\naccess, per key_id, its scopes, credit_limit, credits_used (what runs started with it\nspent), expires_at and expired. scopes is the calling key's. The signup key is key_id\n\"original\". A key itself is never shown again. Needs admin. MCP: list_keys.","operationId":"list_keys_v1_keys_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyList"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"500":{"description":"our fault; names the request id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}}}},"post":{"tags":["keys"],"summary":"Create another API key. The key is in this response only.","description":"A new key on the same account, for example one per agent or machine, so one can be\nrevoked without touching the others. Give it only what it needs: scopes (read, write,\nresearch, admin; all four when left out), credit_limit (the most its runs may spend\nover its life, 1 to 100000) and expires_in_days (1 to 365). The full key is in this\nresponse and nowhere else, ever. Needs admin. 409 key_limit_reached at 10 active\nkeys; creation is limited per account per hour (429). MCP: create_key.","operationId":"create_key_v1_keys_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/KeyIn"},{"type":"null"}],"title":"Body"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyCreatedOut"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"409":{"description":"conflict with the account's state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","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/keys/{key_id}":{"delete":{"tags":["keys"],"summary":"Revoke a key (\"original\", a key_id, or \"others\" for all but yours)","description":"Revoke one key at once. You may revoke the key you are calling with, whatever its\nscopes (the response says so in current); revoking another needs admin. Never the last\nusable key (409 last_active_key: create another first). An unknown or already revoked\nkey is 404 key_not_found. key_id \"others\" revokes every key of the account except the\none calling, for a key that leaked, and answers revoked_count and kept. MCP:\nrevoke_key.","operationId":"revoke_key_v1_keys__key_id__delete","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyRevokedOut"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"404":{"description":"not found on this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"409":{"description":"conflict with the account's state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input","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/research":{"post":{"tags":["research"],"summary":"Find hooks on a topic. Returns immediately; wait on the run.","description":"Start a research run across TikTok and Instagram and return its run_id at once.\nIt reserves up to 200 credits (less on a smaller balance, down to 40) and charges only\nwhat it used; a failed run costs nothing, and so does a run that finds no hooks, within\na per-account allowance (llms.txt has the numbers). A fresh run takes about 2 to 3 minutes (up to about 5 on a dialect request): then\nGET /v1/runs/{run_id}?wait=55 until status is done or failed. Needs research. A key\nwith a credit_limit reserves at most what is left of it (403 key_credit_limit_reached\nunder the minimum). Any language, dialect or country: set language (\"Moroccan\nDarija\", \"ar-MA\") and country (\"MA\"), or say it in the topic. Since 2026-10-01:\nposted_within_days (7, 30, 90 or 365) keeps the search to recent clips, and\nseed_hook_ids (up to 10 of your hooks) means \"find more like these\". Hooks carry\nvirality (the v2 score), outlier (views over the creator's usual), posted_at and\nthe other signals; a done run carries patterns, the structures winning in its deck.\nSince 2026-10-10: platforms (any of \"tiktok\", \"instagram\", \"youtube\"; all three when\nleft out) searches and delivers only those platforms.\nMCP: find_hooks.","operationId":"research_v1_research_post","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"retry safely: the same key within 24 hours returns the first run and reserves nothing","title":"Idempotency-Key"},"description":"retry safely: the same key within 24 hours returns the first run and reserves nothing"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchIn"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunStartedOut"}}}},"200":{"description":"a replay of an earlier start with the same Idempotency-Key; nothing was reserved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunStartedOut"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"402":{"description":"not enough credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"500":{"description":"our fault; names the request id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"429":{"description":"too_many_runs: the account already has the most runs in flight it may; see Retry-After; nothing was reserved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"503":{"description":"nothing was reserved; see Retry-After. search_unavailable: the video search provider is refusing our requests right now. at_capacity: today's research capacity is used up. restarting: this server is restarting for an update. unavailable: every database connection stayed busy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}}}}},"/v1/runs/{run_id}":{"get":{"tags":["research"],"summary":"A run and its hooks","description":"One run: status, progress, reserved, charged, error (ending with the request id\nthat started it, on a failed run) and every hook it produced. ?wait=N holds the\nrequest until the run is done or failed, or N seconds pass. With since set to the\nlast progress.updated_at, it also returns on progress change. A done run with fewer\nhooks than asked for, or none, has outcome: why, in plain words; a full run has none,\nor one sentence on hooks under the view floor. `hooks` holds only clips where a person\non camera is talking; `bonus` is always [] (removed 2026-10-08). Every hook has format\nand section, and since\n2026-10-01 virality, virality_why, outlier, posted_at, age_days, views_per_day and the\nother virality v2 fields (null on older hooks). A done run also carries patterns: up\nto 3 hook structures winning in this deck with the hook_ids using each, computed\nafter delivery (null until then, and on older runs). Free. MCP: get_run.","operationId":"get_run_v1_runs__run_id__get","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}},{"name":"wait","in":"query","required":false,"schema":{"type":"integer","maximum":55,"minimum":0,"description":"seconds to wait for the run to finish, 0 to 55. Returns as soon as it is done or failed.","default":0,"title":"Wait"},"description":"seconds to wait for the run to finish, 0 to 55. Returns as soon as it is done or failed."},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last progress.updated_at; return early when it changes.","title":"Since"},"description":"Last progress.updated_at; return early when it changes."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunOut"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"404":{"description":"not found on this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","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/runs/{run_id}/export":{"get":{"tags":["research"],"summary":"Download a run's hooks as CSV, JSON or Markdown","description":"The hooks of a finished run as a file, one row or section per hook, ready to open\nin a spreadsheet or paste into notes. CSV cells that a spreadsheet would run as a\nformula are prefixed with a quote. With bom=true a csv starts with the UTF-8\nbyte-order mark for Excel. 409 run_not_finished while the run is in flight.\nFree. MCP: export_run.","operationId":"export_run_v1_runs__run_id__export_get","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}},{"name":"format","in":"query","required":false,"schema":{"enum":["csv","json","md"],"type":"string","description":"csv (opens in any spreadsheet), json or md","default":"csv","title":"Format"},"description":"csv (opens in any spreadsheet), json or md"},{"name":"bom","in":"query","required":false,"schema":{"type":"boolean","description":"csv only: start the file with the UTF-8 byte-order mark, so Excel opens it as UTF-8 (curly quotes, emoji, accents). Leave it off when a program reads the file","default":false,"title":"Bom"},"description":"csv only: start the file with the UTF-8 byte-order mark, so Excel opens it as UTF-8 (curly quotes, emoji, accents). Leave it off when a program reads the file"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"responses":{"200":{"description":"the file, as an attachment","content":{"text/csv":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}},"text/markdown":{"schema":{"type":"string"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"404":{"description":"not found on this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"409":{"description":"conflict with the account's state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input","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/runs":{"get":{"tags":["research"],"summary":"Your runs, newest first","description":"Your runs without their results, newest first, a page at a time: pass next_cursor\nback as ?cursor= for the next page (null on the last). Each says its kind (short, long\nor packaging); ?kind= narrows the list to one. Open one with GET /v1/runs/{run_id}.\nFree. MCP: list_runs.","operationId":"list_runs_v1_runs_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"page size, 1 to 100","default":20,"title":"Limit"},"description":"page size, 1 to 100"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"next_cursor from the previous page; leave out for the first","title":"Cursor"},"description":"next_cursor from the previous page; leave out for the first"},{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"only runs of this kind: short, long or packaging; leave out for every kind","title":"Kind"},"description":"only runs of this kind: short, long or packaging; leave out for every kind"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunList"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input","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/longform":{"post":{"tags":["long form"],"summary":"Find long-form hooks: how the YouTube outliers on a topic open.","description":"Start a long-form run and return its run_id at once. It searches YouTube for\nlong-form videos on the topic (never Shorts), keeps only the outliers (videos whose\nviews are at least min_outlier times the median of their own channel's recent uploads,\n2 by default) posted in 2023 or later, reads the first intro_seconds (60 by default) of\neach one's transcript and says why that opening holds a viewer. Then GET\n/v1/runs/{run_id}?wait=55 until status is done or failed: the results are the run's\n`finds`, each with hook and intro (verbatim, timed lines), hook_type, mechanism,\npromise, open_loop, beats, template and steal_it; `report.patterns` says which opening\ntypes several of them share, `report.shape` how the openings are built (how long the\nhook runs, which beats they use and when, counted from the finds) and `report.openers`\nholds up to `openers` (3 by default) openings written for your topic from those\nstructures, always labelled as written, never counted as a find. While it runs,\n`progress.items` holds the finds written so far, as cards, and `progress.scan` the videos it is looking at. It reserves up to 90 credits for 20 videos or fewer and 5 more for each video above that (140 for the largest count, 30; less on a smaller balance, down to 25) and charges\nonly the provider calls it made (the searches, one call per channel measured, one per\ntranscript read); a failed run costs nothing, and so does one that finds nothing, inside\nthe same allowance a hook run has. How long it takes has not been measured yet: poll,\nnever assume a time. A second long or packaging run on the same topic within a week starts from the\nvideos the first one bought (reuse), and a video you already had read is delivered from\nthat read (`analysis_from_earlier_read`).\n\n`topic` may be a YouTube address instead of a subject: a channel's\n(https://www.youtube.com/@name, or @name) returns that channel's own outliers among\nits recent long-form uploads (one provider call, no search), and a long-form video's\nreturns that one video whatever its multiple (`requested` is 1). The run's\n`options.link` says which (\"channel\" or \"video\"); no openings are written for a link.\n`channel_size` (small, medium, large) keeps only channels of that size, by what their\nuploads usually get. `report.landscape` is the subject at a glance, counted. Starts are\nlimited per account per hour (429). Needs research. MCP: find_long_hooks.","operationId":"longform_v1_longform_post","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"retry safely: the same key within 24 hours returns the first run and reserves nothing","title":"Idempotency-Key"},"description":"retry safely: the same key within 24 hours returns the first run and reserves nothing"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LongformIn"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunStartedOut"}}}},"200":{"description":"a replay of an earlier start with the same Idempotency-Key; nothing was reserved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunStartedOut"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"402":{"description":"not enough credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"500":{"description":"our fault; names the request id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"429":{"description":"too_many_runs: the account already has the most runs in flight it may; see Retry-After; nothing was reserved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"503":{"description":"nothing was reserved; see Retry-After. search_unavailable, at_capacity, restarting or unavailable, as on POST /v1/research","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}}}}},"/v1/packaging":{"post":{"tags":["packaging"],"summary":"Find packaging: the titles and thumbnails that earned the click on a topic.","description":"Start a packaging run and return its run_id at once. It finds the long-form YouTube\nvideos on the topic that beat their own channel (the same outlier search as POST\n/v1/longform, 2023 or later), looks at each one's thumbnail beside its title, and\nreturns the pairs as the run's `finds`: title and thumbnail_url (YouTube's own), views\nand outlier, and what the package does: title_device, title_template, thumbnail_text,\nthumbnail_subject, thumbnail_composition, thumbnail_devices and gap (what the picture\nshows that the title does not say). `report` then holds title_patterns and\nthumbnail_patterns (what at least two of them share) and ideas: up to `ideas` (6 by\ndefault) titles and thumbnail concepts written for your topic from those patterns,\nalways labelled as written, never counted as a find, and `numbers`: the packages\ncounted (title length, how many carry a number or a question, how many thumbnails print\nwords, which devices repeat). GET /v1/runs/{run_id}?wait=55 until done; while it runs,\n`progress.items` holds the packages looked at so far, as cards, and `progress.scan` the\nvideos it is looking at. It reserves up to 70 credits for 24 packages or fewer and 3 more for each package above that (88 for the largest count, 30; down to 25) and charges only the provider\ncalls it made (the searches, one call per channel measured, and one for each video whose\ndate had to be read exactly): looking at a thumbnail costs none. A failed run costs\nnothing, and so does one that finds nothing, inside the allowance. How long it takes\nhas not been measured yet: poll, never assume a time. `topic` may be a channel's or a\nvideo's YouTube address, and `channel_size` narrows to channels of one size, exactly as\non POST /v1/longform; no ideas are written for a link. Starts are limited per account\nper hour (429). Needs research. MCP: find_packaging.","operationId":"packaging_v1_packaging_post","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"retry safely: the same key within 24 hours returns the first run and reserves nothing","title":"Idempotency-Key"},"description":"retry safely: the same key within 24 hours returns the first run and reserves nothing"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackagingIn"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunStartedOut"}}}},"200":{"description":"a replay of an earlier start with the same Idempotency-Key; nothing was reserved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunStartedOut"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"402":{"description":"not enough credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"500":{"description":"our fault; names the request id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"429":{"description":"too_many_runs: the account already has the most runs in flight it may; see Retry-After; nothing was reserved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"503":{"description":"nothing was reserved; see Retry-After. search_unavailable, at_capacity, restarting or unavailable, as on POST /v1/research","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}}}}},"/v1/finds":{"get":{"tags":["long form","packaging"],"summary":"The index: every video your long and packaging runs found","description":"Everything your long and packaging runs found, as one index: one entry a video on\neach tab (its newest read, with the keep or reject you made on the video), each a full\nfind object with its title and thumbnail as YouTube shows them, its `outlier` (views\nover its channel's usual) and its `outlier_score` (0 to 100 on one fixed scale, so\nentries from different runs rank together). `q` looks in the title, the channel, the\nhook as it was said, and what the thumbnail prints and shows, so a package can be\nfound by its thumbnail (\"red arrow\", \"before and after\"). `total` is how many entries\nmatch, on any page; page with next_cursor. Free. MCP: list_finds.","operationId":"find_index_v1_finds_get","parameters":[{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"only long or only packaging; leave out for both","title":"Kind"},"description":"only long or only packaging; leave out for both"},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"description":"words a title, channel, hook or thumbnail must hold","title":"Q"},"description":"words a title, channel, hook or thumbnail must hold"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","description":"score (the default: the highest outlier score first), outlier (views over the channel's usual), views or newest","default":"score","title":"Sort"},"description":"score (the default: the highest outlier score first), outlier (views over the channel's usual), views or newest"},{"name":"tier","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"only breakout (10 times the channel's usual or more), strong (5 to 10) or outlier (under 5)","title":"Tier"},"description":"only breakout (10 times the channel's usual or more), strong (5 to 10) or outlier (under 5)"},{"name":"min_score","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"only entries with an outlier_score of at least this, 0 to 100","title":"Min Score"},"description":"only entries with an outlier_score of at least this, 0 to 100"},{"name":"device","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"only entries filed under this device: a hook_type, a title_device or one of the thumbnail_devices (\"curiosity_gap\", \"how_to\", \"face_closeup\")","title":"Device"},"description":"only entries filed under this device: a hook_type, a title_device or one of the thumbnail_devices (\"curiosity_gap\", \"how_to\", \"face_closeup\")"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"page size, 1 to 100","default":100,"title":"Limit"},"description":"page size, 1 to 100"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"next_cursor from the previous page; leave out for the first","title":"Cursor"},"description":"next_cursor from the previous page; leave out for the first"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindIndexOut"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input","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/finds/keeps":{"get":{"tags":["long form","packaging"],"summary":"The long-form hooks and packages you kept","description":"The videos you kept, newest decision first: one entry a video on each tab (its\nnewest find), or the kept finds of one run when run_id is given; full find objects, a\npage at a time. count is the number on this page. Free. MCP: list_kept_finds.","operationId":"kept_finds_v1_finds_keeps_get","parameters":[{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"only long or only packaging; leave out for both","title":"Kind"},"description":"only long or only packaging; leave out for both"},{"name":"run_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"page size, 1 to 100","default":100,"title":"Limit"},"description":"page size, 1 to 100"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"next_cursor from the previous page; leave out for the first","title":"Cursor"},"description":"next_cursor from the previous page; leave out for the first"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeptFindsOut"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input","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/finds/{find_id}":{"get":{"tags":["long form","packaging"],"summary":"One find, every field","description":"One result of a long or packaging run with every field. find_id comes from a run's\n`finds`. Free. MCP: get_find.","operationId":"get_find_v1_finds__find_id__get","parameters":[{"name":"find_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Find Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindOut"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"404":{"description":"not found on this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input","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/finds/{find_id}/decision":{"post":{"tags":["long form","packaging"],"summary":"Keep or reject a find","description":"Record keep or reject on one find; the last verdict wins. The verdict is the video's\non that tab: every find of the same video you have there (an earlier run's, a later\none's) carries it. Kept videos come back from GET /v1/finds/keeps. Free. MCP: keep_find.","operationId":"decide_find_v1_finds__find_id__decision_post","parameters":[{"name":"find_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Find Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindDecisionOut"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"404":{"description":"not found on this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"500":{"description":"our fault; names the request id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}}}},"delete":{"tags":["long form","packaging"],"summary":"Clear a keep or reject on a find","description":"Undo a verdict: the video goes back to having none, on every find of it, and leaves\nGET /v1/finds/keeps. Answers {\"find_id\", \"verdict\": null}. Clearing a find with no\ndecision is the same 200. Free. MCP: clear_find_decision.","operationId":"clear_find_decision_v1_finds__find_id__decision_delete","parameters":[{"name":"find_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Find Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindDecisionOut"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"404":{"description":"not found on this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input","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/finds/{find_id}/remix":{"post":{"tags":["long form","packaging"],"summary":"Make it mine, or Write my intro: written from this find","description":"Write my intro: body {\"mode\": \"intro\", \"video_brief\": \"\"} (a long find only; niche and n are not used) writes\nyour own intro in this real opening's structure: one entry in `written` holding a\n`beat` for each beat of the real opening, in order, each with its seconds (from_s,\nto_s) and words_budget taken from the real opening's own timing, the words to `say`\nwith {placeholders} for what only you know, and suggested_on_screen and suggested_broll\n(suggestions, never part of what is said). A number you did not write becomes {number}\n(numbers_to_placeholders counts them). Same price and rules as below: 1 credit, labelled\nas written, 422 remix_not_possible when the model copied the real opening or broke a\nbudget.\n\nOtherwise write up to n (1 to 5, default 3) new openings or packages for your niche\nthat keep this one real find's structure. From a long find: `written` holds openings (hook, then,\nkept_structure) built on its template and its order of beats. From a packaging find:\npackages (title, thumbnail, thumbnail_text, kept_structure) built on its title\ntemplate and its thumbnail's composition. Body: {\"niche\": \"teeth whitening\", \"n\": 2}.\nEvery answer carries `label`: these are written, never found; one that is the real\nfind's own words is dropped; they are never added to a run, a keep or an export. Costs\n1 credit per call, taken before the model is asked and refunded if it does not answer\n(503). 404 for a find that is not yours. Limited per account per hour (429). Needs\nresearch. The answer carries remix_id; GET /v1/finds/{find_id}/remixes and GET\n/v1/remixes/{remix_id} read it back, free. MCP: remix_find.","operationId":"remix_find_v1_finds__find_id__remix_post","parameters":[{"name":"find_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Find Id"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"retry safely: the same key and body within 24 hours answer the saved remix (Idempotent-Replayed: true) and charge nothing; the same key with another body is 422 idempotency_key_reused","title":"Idempotency-Key"},"description":"retry safely: the same key and body within 24 hours answer the saved remix (Idempotent-Replayed: true) and charge nothing; the same key with another body is 422 idempotency_key_reused"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/RemixFindIn"},{"type":"null"}],"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixFindOut"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"402":{"description":"not enough credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"404":{"description":"not found on this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input (invalid_request, idempotency_key_reused), or remix_not_possible: the model answered but nothing it wrote kept the rules, or it declined the content; detail says why and the credit was refunded","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"}}}},"503":{"description":"model_unavailable: the language model did not answer; the credit was refunded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}}}}},"/v1/finds/{find_id}/remixes":{"get":{"tags":["long form","packaging"],"summary":"Your saved remixes of this find","description":"The openings or packages you paid to have written from this find, newest first,\neach as its answer held it, with remix_id and created_at. Free. 404 for a find that is\nnot yours. MCP: list_remixes.","operationId":"find_remixes_v1_finds__find_id__remixes_get","parameters":[{"name":"find_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Find Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemixList"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"404":{"description":"not found on this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input","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/remixes/{remix_id}":{"get":{"tags":["hooks"],"summary":"One saved remix","description":"One remix you paid for (a hook's or a find's), as its answer held it. Free. 404\nremix_not_found for one that is not yours. MCP: get_remix.","operationId":"get_remix_v1_remixes__remix_id__get","parameters":[{"name":"remix_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Remix Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedRemixOut"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"404":{"description":"not found on this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input","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/hooks/{hook_id}":{"get":{"tags":["hooks"],"summary":"One hook, every field","description":"One hook with every field: the verbatim opening line, the most quotable line, main\nidea, why it travelled, on-screen text, transcript, watch_url and the 9:16\nplayer_url. hook_id comes from a run. Free. MCP: get_hook.","operationId":"get_hook_v1_hooks__hook_id__get","parameters":[{"name":"hook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Hook Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookOut"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"404":{"description":"not found on this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input","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/hooks/{hook_id}/embed":{"get":{"tags":["hooks"],"summary":"Playable embed so the clip runs in your page","description":"Official TikTok or Instagram embed HTML. kind is \"embed\", or \"fallback\" when the\ncreator disabled embedding or the clip is a photo post found before 2026-09-26 (then\nshow thumbnail, which\nfalls back to the hook's still_url, and the transcript; a fallback is remembered for\nan hour). For a plain vertical player use the hook's player_url.\nFree. MCP: embed_hook.","operationId":"get_embed_v1_hooks__hook_id__embed_get","parameters":[{"name":"hook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Hook Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys","title":"Authorization"},"description":"Bearer hd_... from POST /v1/accounts or POST /v1/keys"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbedOut"}}}},"401":{"description":"missing, invalid, revoked or expired API key (code key_expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"403":{"description":"the key lacks the scope this call needs (insufficient_scope), or its credit_limit is spent (key_credit_limit_reached)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"404":{"description":"not found on this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"413":{"description":"request body over the size cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorOut"}}}},"422":{"description":"invalid input","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/hooks/{hook_id}/still":{"get":{"tags":["hooks"],"summary":"The hook's still as a JPEG, for an tag","description":"The card image for a hook, fetched and re-encoded by this API, so it loads on any\npage (platform image hosts refuse to be shown on other sites, and their links expire).\nNo key needed: the id comes from a run and the image is the platform's public still.\nCached for a day. Free. On MCP the same URL is the hook's still_url.","operationId":"get_still_v1_hooks__hook_id__still_get","parameters":[{"name":"hook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Hook Id"}}],"responses":{"200":{"description":"the still as a JPEG","content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}}}},"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/hooks/{hook_id}/media":{"get":{"tags":["hooks"],"summary":"The clip's original video file, for a