{"openapi":"3.0.0","info":{"title":"Hookest API","version":"1.0.0","description":"Hookest public API. Hook catalog, short-form video scoring, and credit wallet."},"servers":[{"url":"https://api.hookest.com"}],"tags":[{"name":"Wallet","description":"Monthly and top-up credit balances."},{"name":"Hooks","description":"Scored hook catalog."},{"name":"Predict","description":"Upload a short clip and score it."},{"name":"Webhooks","description":"Account webhook URL and secret for prediction results."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key as `Authorization: Bearer hk_live_...`. Query-string keys are rejected."}},"schemas":{"Wallet":{"type":"object","properties":{"object":{"type":"string","enum":["wallet"]},"monthly_balance":{"type":"integer"},"monthly_period_end":{"type":"string","nullable":true},"topup_balance":{"type":"integer"}},"required":["object","monthly_balance","monthly_period_end","topup_balance"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","example":"invalid_api_key"},"message":{"type":"string"},"request_id":{"type":"string","example":"req_4f8c2a"}},"required":["type","message","request_id"]}},"required":["error"]},"HookCategoryList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/HookCategory"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}},"required":["object","data","has_more","next_cursor"]},"HookCategory":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"}},"required":["slug","name"]},"HookList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/HookLean"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}},"required":["object","data","has_more","next_cursor"]},"HookLean":{"type":"object","properties":{"id":{"type":"string","example":"hook_9f2a1c"},"text":{"type":"string"},"platform":{"type":"string"},"media_type":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"hook_duration_sec":{"type":"number","nullable":true},"published_at":{"type":"string","nullable":true}},"required":["id","text","platform","media_type","thumbnail_url","category","hook_duration_sec","published_at"]},"HookRich":{"allOf":[{"$ref":"#/components/schemas/HookLean"},{"type":"object","properties":{"source_url":{"type":"string","nullable":true},"caption":{"type":"string","nullable":true},"duration_sec":{"type":"number","nullable":true},"summary":{"type":"string","nullable":true},"emotions":{"type":"object","nullable":true,"properties":{"inspiration":{"type":"number"},"fear":{"type":"number"},"curiosity":{"type":"number"},"satisfaction":{"type":"number"},"happiness":{"type":"number"},"anger":{"type":"number"},"surprise":{"type":"number"}}},"comment_themes":{"type":"array","nullable":true,"items":{"type":"object","properties":{"word":{"type":"string"},"count":{"type":"number"}},"required":["word","count"]}},"metrics":{"type":"object","nullable":true,"properties":{}},"creator":{"type":"object","nullable":true,"properties":{}},"audio":{"type":"object","nullable":true,"properties":{}}},"required":["source_url","caption","duration_sec","summary","emotions","comment_themes","metrics","creator","audio"]}]},"PredictUpload":{"type":"object","properties":{"upload_id":{"type":"string"},"prediction_id":{"type":"string"},"upload_url":{"type":"string"},"expires_at":{"type":"string"}},"required":["upload_id","prediction_id","upload_url","expires_at"]},"Prediction":{"type":"object","properties":{"object":{"type":"string","enum":["prediction"]},"id":{"type":"string","example":"pred_7b3e"},"status":{"type":"string","enum":["awaiting_upload","queued","running","succeeded","failed"]},"created_at":{"type":"string"},"completed_at":{"type":"string","nullable":true},"input":{"type":"object","nullable":true,"properties":{"duration_sec":{"type":"number","nullable":true}},"required":["duration_sec"]},"result":{"type":"object","nullable":true,"properties":{"band":{"type":"string"},"hook_duration_sec":{"type":"number","nullable":true},"category":{"type":"object","nullable":true,"properties":{"slug":{"type":"string"}},"required":["slug"]}},"required":["band","hook_duration_sec","category"]},"error":{"type":"object","nullable":true,"properties":{"type":{"type":"string"},"message":{"type":"string"}},"required":["type","message"]}},"required":["object","id","status","created_at","completed_at","input","result","error"]},"Webhook":{"type":"object","properties":{"object":{"type":"string","enum":["webhook"]},"url":{"type":"string","nullable":true},"configured":{"type":"boolean"}},"required":["object","url","configured"]},"WebhookSecret":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","properties":{"secret":{"type":"string"}}}]},"WebhookTest":{"type":"object","properties":{"object":{"type":"string","enum":["webhook_test"]},"delivered":{"type":"boolean"},"status_code":{"type":"number","nullable":true},"event":{"type":"string","enum":["prediction.succeeded"]}},"required":["object","delivered","status_code","event"]}},"parameters":{}},"paths":{"/v1/wallet":{"get":{"operationId":"getWallet","summary":"Get wallet balances","tags":["Wallet"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Monthly and top-up balances, returned separately. 0 credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Wallet"}}}},"400":{"description":"invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled | account_suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/categories":{"get":{"operationId":"listHookCategories","summary":"List hook categories","tags":["Hooks"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Category slug list. 0 credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookCategoryList"}}}},"400":{"description":"invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled | account_suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/search":{"get":{"operationId":"searchHooks","summary":"Search hooks","tags":["Hooks"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":200},"required":true,"name":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Lean list. Credits charged are ceil(rows / 25).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookList"}}}},"400":{"description":"invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled | account_suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/list":{"get":{"operationId":"listHooks","summary":"List hooks by category","tags":["Hooks"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"required":true,"name":"category","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Lean list. Credits charged are ceil(rows / 25).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookList"}}}},"400":{"description":"invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled | account_suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hooks/{id}":{"get":{"operationId":"getHook","summary":"Get a hook","tags":["Hooks"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Rich record. 1 credit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HookRich"}}}},"400":{"description":"invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled | account_suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/predict/upload":{"post":{"operationId":"createUploadLink","summary":"Create an upload link","tags":["Predict"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"One-time upload_url + prediction_id. 0 credits. No file on this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictUpload"}}}},"400":{"description":"invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled | account_suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/predict":{"post":{"operationId":"retryPrediction","summary":"Retry prediction start","tags":["Predict"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"upload_id":{"type":"string"}},"required":["upload_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Retry consume if the file landed but the job stayed awaiting_upload. Already queued returns the same prediction; X-Credits-Charged is 0 then.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Prediction"}}}},"400":{"description":"invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled | account_suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/predict/{id}":{"get":{"operationId":"getPrediction","summary":"Get a prediction","tags":["Predict"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Job status. 0 credits. Same key only. 24 hours. 404 otherwise.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Prediction"}}}},"400":{"description":"invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled | account_suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks":{"get":{"operationId":"getWebhook","summary":"Get the account webhook","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Account webhook. 0 credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"400":{"description":"invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled | account_suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"upsertWebhook","summary":"Set the webhook URL","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":false}}}},"responses":{"200":{"description":"Set the URL. The secret is returned only on create. 0 credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSecret"}}}},"400":{"description":"invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled | account_suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteWebhook","summary":"Disable the webhook","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Disable the URL. 0 credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"400":{"description":"invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled | account_suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/rotate":{"post":{"operationId":"rotateWebhookSecret","summary":"Rotate the webhook secret","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"New secret, shown once. 0 credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSecret"}}}},"400":{"description":"invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled | account_suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/test":{"post":{"operationId":"sendWebhookTest","summary":"Send a test webhook","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Send a synthetic prediction.succeeded event. 0 credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTest"}}}},"400":{"description":"invalid_cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled | account_suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}