{"openapi":"3.1.0","info":{"title":"HuntAPI API Reference","description":"Complete API reference documentation.","version":"1.0.0"},"servers":[{"url":"https://api.huntapi.com","description":"API Server"}],"paths":{"/v1/stats":{"get":{"summary":"Stats","description":"Infrastructure health for an engine or endpoint over the last hour. Not scoped to your account or tenant. Enabled per account: HTTP 403 means contact support to activate it.","operationId":"stats","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"engine","in":"query","required":false,"description":"API family to check, for example `video`. Provide at least `engine` or `path`.","schema":{"type":"string","description":"API family to check, for example `video`. Provide at least `engine` or `path`."}},{"name":"path","in":"query","required":false,"description":"Specific endpoint to check, for example `/v1/video/download`. If you also pass `engine`, use an endpoint from that API.","schema":{"type":"string","description":"Specific endpoint to check, for example `/v1/video/download`. If you also pass `engine`, use an endpoint from that API."}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"nullable":true},"engine":{"type":"string"},"health":{"type":"string"},"window":{"type":"string"},"success_rate":{"type":"number"},"avg_response_time_ms":{"type":"integer"}}},"examples":{"Engine health snapshot":{"value":{"path":null,"engine":"video","health":"operational","window":"1h","success_rate":99.412,"avg_response_time_ms":840}},"Path health snapshot":{"value":{"path":"/v1/video/download","engine":"video","health":"operational","window":"1h","success_rate":99.412,"avg_response_time_ms":840}}}}}},"400":{"description":"Bad Request — missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad Request"}}}},"401":{"description":"Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid API Key"}},"planRateLimit":{"value":{"error":"Rate limit exceeded: You've exceeded the per second rate limit on your subscription"}},"keyQuota":{"value":{"error":"Rate limit exceeded for the API key: quota monthly"}}}}}},"402":{"description":"Payment Required — your subscription or credit balance is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Payment required"}}}},"500":{"description":"Internal Server Error — something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal Error"}}}}}}},"/v1/media/metadata":{"get":{"summary":"Media Metadata","description":"Extract metadata from a media URL without downloading the file.\n\n**Credit cost:** 1 credit per call","operationId":"media-metadata","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"description":"Media URL to inspect (YouTube, Instagram, TikTok, Vimeo, X, Facebook, Twitch, Reddit, etc.).\n\nReturns title, duration, thumbnail, channel, view counts and related metadata **without downloading** the file.\n\n**Notes:** Some URLs cannot be inspected for the following reasons:\n\n- **Private content**\n- **Unavailable / deleted content**\n- **Age restricted content**\n\nIn these cases, the API returns an explanatory error message.","schema":{"type":"string","description":"Media URL to inspect (YouTube, Instagram, TikTok, Vimeo, X, Facebook, Twitch, Reddit, etc.).\n\nReturns title, duration, thumbnail, channel, view counts and related metadata **without downloading** the file.\n\n**Notes:** Some URLs cannot be inspected for the following reasons:\n\n- **Private content**\n- **Unavailable / deleted content**\n- **Age restricted content**\n\nIn these cases, the API returns an explanatory error message."}},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/is_async"},{"$ref":"#/components/parameters/soft_fail"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","properties":{"id":{"type":"string"},"ext":{"type":"string"},"title":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"channel":{"type":"string"},"is_live":{"type":"boolean"},"duration":{"type":"integer"},"was_live":{"type":"boolean"},"extractor":{"type":"string"},"thumbnail":{"type":"string"},"like_count":{"type":"integer"},"view_count":{"type":"integer"},"channel_url":{"type":"string"},"description":{"type":"string"},"live_status":{"type":"string"},"upload_date":{"type":"integer"},"webpage_url":{"type":"string"},"original_url":{"type":"string"}}}}},"examples":{"YouTube metadata":{"value":{"metadata":{"id":"3g3Eow41B6I","ext":"mp4","title":"Faire une interview Multicam avec UNE SEULE caméra","width":640,"height":360,"channel":"Alex Jackson","is_live":false,"duration":432,"was_live":false,"extractor":"Youtube","thumbnail":"https://i.ytimg.com/vi/3g3Eow41B6I/maxresdefault.jpg","like_count":4060,"view_count":93297,"channel_url":"https://www.youtube.com/channel/UCW0GdGxlRENND_ft84Cp5vg","description":"🎁 Starter Pack DaVinci Resolve GRATUIT : https://formations.alexjackson.io/starter-pack-davinci-resolve","live_status":"not_live","upload_date":1712188800,"webpage_url":"https://www.youtube.com/watch?v=3g3Eow41B6I","original_url":"https://www.youtube.com/watch?v=3g3Eow41B6I"}}}}}}},"400":{"description":"Bad Request — missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad Request"}}}},"401":{"description":"Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid API Key"}},"planRateLimit":{"value":{"error":"Rate limit exceeded: You've exceeded the per second rate limit on your subscription"}},"keyQuota":{"value":{"error":"Rate limit exceeded for the API key: quota monthly"}}}}}},"402":{"description":"Payment Required — your subscription or credit balance is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Payment required"}}}},"500":{"description":"Internal Server Error — something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal Error"}}}}}}},"/v1/usage":{"get":{"summary":"Usage","description":"Retrieve real-time usage statistics and credit balance for your Huntapi account.","operationId":"usage","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"packs":{"nullable":true},"period":{"type":"object","properties":{"end":{"type":"string"},"start":{"type":"string"}}},"account":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"api_key":{"type":"object","properties":{"alias":{"type":"string"},"active":{"type":"boolean"},"quotas":{"type":"object","properties":{"daily":{"nullable":true},"total":{"nullable":true},"weekly":{"nullable":true},"monthly":{"nullable":true}}},"expires":{"nullable":true},"category":{"type":"string"}}},"credits":{"type":"object","properties":{"given":{"type":"integer"},"consumed":{"type":"integer"},"remaining":{"type":"integer"},"percent_used":{"type":"integer"}}},"remaining":{"type":"integer"},"rate_limit":{"type":"object","properties":{"per_minute":{"nullable":true},"per_second":{"nullable":true}}},"total_used":{"type":"integer"},"renewal_date":{"type":"string"},"subscription":{"type":"object","properties":{"used":{"type":"integer"},"total":{"type":"integer"},"remaining":{"type":"integer"},"percent_used":{"type":"integer"}}}}},"examples":{"Account usage overview":{"value":{"packs":null,"period":{"end":"2026-04-25","start":"2026-03-25"},"account":{"name":"Microsoft","slug":"microsoft"},"api_key":{"alias":"my-api-key","active":true,"quotas":{"daily":null,"total":null,"weekly":null,"monthly":null},"expires":null,"category":"development"},"credits":{"given":0,"consumed":0,"remaining":0,"percent_used":0},"remaining":0,"rate_limit":{"per_minute":null,"per_second":null},"total_used":15871,"renewal_date":"2026-04-25","subscription":{"used":15871,"total":50,"remaining":0,"percent_used":31742}}},"Account with one-time packs":{"value":{"packs":{"used":15200000,"count":2,"items":[{"id":"cmhtn…","used":12500000,"title":"Ultimate","total":12500000,"exhausted":true,"remaining":0,"percent_used":100,"purchased_at":"2025-11-10"},{"id":"cmlc9…","used":2700000,"title":"Ultimate","total":12500000,"exhausted":false,"remaining":9800000,"percent_used":21.6,"purchased_at":"2026-02-07"}],"total":25000000,"current":{"id":"cmlc9…","used":2700000,"title":"Ultimate","total":12500000,"exhausted":false,"remaining":9800000,"percent_used":21.6,"purchased_at":"2026-02-07"},"remaining":9800000,"percent_used":60.8,"all_exhausted":false,"current_index":2,"exhausted_count":1},"period":{"end":"2026-10-01","start":"2026-09-01"},"account":{"name":"Microsoft","slug":"microsoft"},"api_key":{"alias":"my-api-key","active":true,"quotas":{"daily":null,"total":null,"weekly":null,"monthly":null},"expires":null,"category":"development"},"credits":{"given":0,"consumed":0,"remaining":0,"percent_used":0},"remaining":9800000,"rate_limit":{"per_minute":null,"per_second":null},"total_used":15200000,"renewal_date":"2026-10-01","subscription":{"used":15200000,"total":25000000,"remaining":9800000,"percent_used":60.8}}}}}}},"400":{"description":"Bad Request — missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad Request"}}}},"401":{"description":"Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid API Key"}},"planRateLimit":{"value":{"error":"Rate limit exceeded: You've exceeded the per second rate limit on your subscription"}},"keyQuota":{"value":{"error":"Rate limit exceeded for the API key: quota monthly"}}}}}},"402":{"description":"Payment Required — your subscription or credit balance is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Payment required"}}}},"500":{"description":"Internal Server Error — something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal Error"}}}}}}},"/v1/jobs/{id}":{"get":{"summary":"Jobs","description":"Poll status, progress (0–100), and result of an async HuntAPI job.","operationId":"jobs-id","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Job UUID returned as `job_id` by async endpoints such as `/v1/video/download` and `/v1/audio/download`.\n\nPoll this endpoint until `status` is terminal (`CompletedJob`, `Error`, `NotFound`, or `BadRequest`). While the job runs, use `progress` (0–100) to show a progress bar.","schema":{"type":"string","description":"Job UUID returned as `job_id` by async endpoints such as `/v1/video/download` and `/v1/audio/download`.\n\nPoll this endpoint until `status` is terminal (`CompletedJob`, `Error`, `NotFound`, or `BadRequest`). While the job runs, use `progress` (0–100) to show a progress bar."}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"args":{"type":"object","properties":{"query":{"type":"string"},"video_format":{"type":"string"},"download_type":{"type":"string"},"video_quality":{"type":"string"}}},"result":{"nullable":true},"status":{"type":"string"},"success":{"nullable":true},"endpoint":{"type":"string"},"progress":{"type":"integer"},"created_at":{"type":"string"},"started_at":{"type":"string"},"duration_ms":{"nullable":true},"completed_at":{"nullable":true}}},"examples":{"Running (with progress)":{"value":{"id":"019ff14c-49fe-09b5-0cd5-e6c575481a6b","args":{"query":"https://www.youtube.com/watch?v=Z5YP8kznWZs","video_format":"mp4","download_type":"audio_video","video_quality":"720p"},"result":null,"status":"Running","success":null,"endpoint":"/api/video/download","progress":63,"created_at":"2026-08-11T14:48:56.574227Z","started_at":"2026-08-11T14:48:56.577590Z","duration_ms":null,"completed_at":null}},"Completed":{"value":{"id":"0193305e-e144-a995-3acc-6703bb48e13a","args":{"query":"https://www.youtube.com/watch?v=example"},"result":{"metadata":{"title":"The New Claude 3.5 Sonnet","view_count":82398,"upload_date":1729641600},"response":"https://s3.huntapi.com/videos/32f88fc4-e728-4c45-b27c-6ee539575595.webm"},"status":"CompletedJob","success":true,"endpoint":"/api/video/download","progress":100,"created_at":"2024-11-15T15:09:04.709497Z","started_at":"2024-11-15T15:09:04.714422Z","duration_ms":99592,"completed_at":"2024-11-15T15:10:44.268Z"}},"Queued":{"value":{"id":"0193443f-fb80-9d19-29ba-82bc77c7cd8c","args":{"query":"https://www.youtube.com/watch?v=example"},"result":null,"status":"Queued","success":null,"endpoint":"/api/video/download","progress":0,"created_at":"2024-11-19T11:47:44.127229Z","started_at":null,"duration_ms":null,"completed_at":null}}}}}},"400":{"description":"Bad Request — missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad Request"}}}},"401":{"description":"Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid API Key"}},"planRateLimit":{"value":{"error":"Rate limit exceeded: You've exceeded the per second rate limit on your subscription"}},"keyQuota":{"value":{"error":"Rate limit exceeded for the API key: quota monthly"}}}}}},"402":{"description":"Payment Required — your subscription or credit balance is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Payment required"}}}},"500":{"description":"Internal Server Error — something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal Error"}}}}}}},"/v1/audio/download":{"get":{"summary":"Audio Download","description":"Download audio from a URL via HuntAPI and receive a job id.\n\n**Credit cost:** 1 credit per call\n\n**Async:** This endpoint runs asynchronously. Use the jobs endpoint to poll for results.","operationId":"get-audio-download","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"description":"URL to download audio from.\n\n**Notes:** Some audios cannot be downloaded for the following reasons:\n\n- **Private content:** If the content is set as private by its owner\n\n- **Unavailable content:** If the content has been deleted or is no longer accessible\n\n- **Age restricted content:** If the content is age restricted In these cases, the API will return an explanatory error message.","schema":{"type":"string","description":"URL to download audio from.\n\n**Notes:** Some audios cannot be downloaded for the following reasons:\n\n- **Private content:** If the content is set as private by its owner\n\n- **Unavailable content:** If the content has been deleted or is no longer accessible\n\n- **Age restricted content:** If the content is age restricted In these cases, the API will return an explanatory error message."}},{"name":"download_type","in":"query","required":false,"description":"Desired download type. Supported values: `audio` (default).","schema":{"type":"string","default":"audio","description":"Desired download type. Supported values: `audio` (default)."}},{"name":"max_duration","in":"query","required":false,"description":"Maximum duration of the downloaded content in seconds. If the audio is longer than this value, only the content up to this duration will be downloaded.","schema":{"type":"number","description":"Maximum duration of the downloaded content in seconds. If the audio is longer than this value, only the content up to this duration will be downloaded."}},{"name":"audio_quality","in":"query","required":false,"description":"Desired audio quality. \n\nAvailable options:\n\n- `best`: Best available quality (default)\n\n- `320kbps`: High quality\n\n- `256kbps`: Standard quality\n\n- `128kbps`: Low quality","schema":{"type":"string","default":"best","description":"Desired audio quality. \n\nAvailable options:\n\n- `best`: Best available quality (default)\n\n- `320kbps`: High quality\n\n- `256kbps`: Standard quality\n\n- `128kbps`: Low quality"}},{"name":"audio_format","in":"query","required":false,"description":"Desired output format for the audio. \n\nAvailable options:\n\n- `mp3`: MP3 format (default option)\n\n- `m4a`: MPEG-4 Audio format\n\n- `wav`: Waveform Audio File Format\n\n**Note:** This is a format preference. While we will do our best to provide the requested format, due to technical limitations or conversion issues, the final output format may differ from the requested one.","schema":{"type":"string","default":"mp3","description":"Desired output format for the audio. \n\nAvailable options:\n\n- `mp3`: MP3 format (default option)\n\n- `m4a`: MPEG-4 Audio format\n\n- `wav`: Waveform Audio File Format\n\n**Note:** This is a format preference. While we will do our best to provide the requested format, due to technical limitations or conversion issues, the final output format may differ from the requested one."}},{"name":"webhook_url","in":"query","required":false,"description":"URL of the webhook where results will be sent. When specified, the system will attempt to send the response to this URL up to 3 times with a 5-second delay between each attempt. \nThe results will be sent as a POST request.\n\nThe payload will be sent in JSON format with one of the following structures:\n\nOn **success**:\n```json\n{\n    \"id\": \"string\", // the job id,\n    \"status\": \"CompletedJob\", // the job status,\n    \"result\": {\n        \"metadata\": {\n            // filtered metadata object\n        },\n        \"response\": \"https://s3.huntapi.com/audios/audio_id.mp3\"\n    }\n}\n```\n\nOn **error**:\n```json\n{\n    \"id\": \"string\", // the job id,\n    \"status\": \"Error\", // the job status,\n    \"error\": \"string\" // the error message (private, unavailable, age restricted, etc.)\n}\n```","schema":{"type":"string","description":"URL of the webhook where results will be sent. When specified, the system will attempt to send the response to this URL up to 3 times with a 5-second delay between each attempt. \nThe results will be sent as a POST request.\n\nThe payload will be sent in JSON format with one of the following structures:\n\nOn **success**:\n```json\n{\n    \"id\": \"string\", // the job id,\n    \"status\": \"CompletedJob\", // the job status,\n    \"result\": {\n        \"metadata\": {\n            // filtered metadata object\n        },\n        \"response\": \"https://s3.huntapi.com/audios/audio_id.mp3\"\n    }\n}\n```\n\nOn **error**:\n```json\n{\n    \"id\": \"string\", // the job id,\n    \"status\": \"Error\", // the job status,\n    \"error\": \"string\" // the error message (private, unavailable, age restricted, etc.)\n}\n```"}},{"name":"webhook_authorization","in":"query","required":false,"description":"Authorization header for the webhook. This parameter allows you to add authentication to your webhook endpoint.\n\nThis value will be included in the **`Authorization`** header when making the webhook request to your server. \n\nExample:\n```\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\n```","schema":{"type":"string","description":"Authorization header for the webhook. This parameter allows you to add authentication to your webhook endpoint.\n\nThis value will be included in the **`Authorization`** header when making the webhook request to your server. \n\nExample:\n```\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\n```"}},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/is_async"},{"$ref":"#/components/parameters/soft_fail"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"}}},"examples":{"Example 1":{"value":{"job_id":"0193443f-fb80-9d19-29ba-82bc77c7cd85"}}}}}},"400":{"description":"Bad Request — missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad Request"}}}},"401":{"description":"Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid API Key"}},"planRateLimit":{"value":{"error":"Rate limit exceeded: You've exceeded the per second rate limit on your subscription"}},"keyQuota":{"value":{"error":"Rate limit exceeded for the API key: quota monthly"}}}}}},"402":{"description":"Payment Required — your subscription or credit balance is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Payment required"}}}},"500":{"description":"Internal Server Error — something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal Error"}}}}}},"post":{"summary":"Audio Download","description":"Download audio from a URL via HuntAPI and receive a job id.\n\n**Credit cost:** 1 credit per call\n\n**Async:** This endpoint runs asynchronously. Use the jobs endpoint to poll for results.","operationId":"post-audio-download","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/is_async"},{"$ref":"#/components/parameters/soft_fail"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"URL to download audio from.\n\n**Notes:** Some audios cannot be downloaded for the following reasons:\n\n- **Private content:** If the content is set as private by its owner\n\n- **Unavailable content:** If the content has been deleted or is no longer accessible\n\n- **Age restricted content:** If the content is age restricted In these cases, the API will return an explanatory error message."},"download_type":{"type":"string","default":"audio","description":"Desired download type. Supported values: `audio` (default)."},"max_duration":{"type":"number","description":"Maximum duration of the downloaded content in seconds. If the audio is longer than this value, only the content up to this duration will be downloaded."},"audio_quality":{"type":"string","default":"best","description":"Desired audio quality. \n\nAvailable options:\n\n- `best`: Best available quality (default)\n\n- `320kbps`: High quality\n\n- `256kbps`: Standard quality\n\n- `128kbps`: Low quality"},"audio_format":{"type":"string","default":"mp3","description":"Desired output format for the audio. \n\nAvailable options:\n\n- `mp3`: MP3 format (default option)\n\n- `m4a`: MPEG-4 Audio format\n\n- `wav`: Waveform Audio File Format\n\n**Note:** This is a format preference. While we will do our best to provide the requested format, due to technical limitations or conversion issues, the final output format may differ from the requested one."},"webhook_url":{"type":"string","description":"URL of the webhook where results will be sent. When specified, the system will attempt to send the response to this URL up to 3 times with a 5-second delay between each attempt. \nThe results will be sent as a POST request.\n\nThe payload will be sent in JSON format with one of the following structures:\n\nOn **success**:\n```json\n{\n    \"id\": \"string\", // the job id,\n    \"status\": \"CompletedJob\", // the job status,\n    \"result\": {\n        \"metadata\": {\n            // filtered metadata object\n        },\n        \"response\": \"https://s3.huntapi.com/audios/audio_id.mp3\"\n    }\n}\n```\n\nOn **error**:\n```json\n{\n    \"id\": \"string\", // the job id,\n    \"status\": \"Error\", // the job status,\n    \"error\": \"string\" // the error message (private, unavailable, age restricted, etc.)\n}\n```"},"webhook_authorization":{"type":"string","description":"Authorization header for the webhook. This parameter allows you to add authentication to your webhook endpoint.\n\nThis value will be included in the **`Authorization`** header when making the webhook request to your server. \n\nExample:\n```\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\n```"}},"required":["query"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"}}},"examples":{"Example 1":{"value":{"job_id":"0193443f-fb80-9d19-29ba-82bc77c7cd85"}}}}}},"400":{"description":"Bad Request — missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad Request"}}}},"401":{"description":"Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid API Key"}},"planRateLimit":{"value":{"error":"Rate limit exceeded: You've exceeded the per second rate limit on your subscription"}},"keyQuota":{"value":{"error":"Rate limit exceeded for the API key: quota monthly"}}}}}},"402":{"description":"Payment Required — your subscription or credit balance is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Payment required"}}}},"500":{"description":"Internal Server Error — something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal Error"}}}}}}},"/v1/video/download":{"get":{"summary":"Video Download","description":"**Credit cost:** 1 credit per call\n\n**Async:** This endpoint runs asynchronously. Use the jobs endpoint to poll for results.","operationId":"get-video-download","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"description":"Video URL to download.\n\n**Notes:**  Some videos cannot be downloaded for the following reasons:\n\n- **Private videos:** If the video is set as private by its owner\n\n- **Unavailable videos:** If the video has been deleted or is no longer accessible\n\n- **Age restricted videos:** If the video is age restricted. In these cases, the API will return an explanatory error message.","schema":{"type":"string","description":"Video URL to download.\n\n**Notes:**  Some videos cannot be downloaded for the following reasons:\n\n- **Private videos:** If the video is set as private by its owner\n\n- **Unavailable videos:** If the video has been deleted or is no longer accessible\n\n- **Age restricted videos:** If the video is age restricted. In these cases, the API will return an explanatory error message."}},{"name":"download_type","in":"query","required":false,"description":"Desired download type. You have three options:\n\n- `audio_video`: Downloads the complete video with audio (default option)\n\n- `audio`: Downloads only the audio track of the video (useful for extracting music or podcasts)\n\n- `video`: Downloads only the video part, without sound (ideal for visual content only)","schema":{"type":"string","default":"audio_video","description":"Desired download type. You have three options:\n\n- `audio_video`: Downloads the complete video with audio (default option)\n\n- `audio`: Downloads only the audio track of the video (useful for extracting music or podcasts)\n\n- `video`: Downloads only the video part, without sound (ideal for visual content only)"}},{"name":"max_duration","in":"query","required":false,"description":"Maximum duration of the downloaded content in seconds.  \nIf the video/audio is longer than this value, only the content up to this duration will be downloaded.","schema":{"type":"number","description":"Maximum duration of the downloaded content in seconds.  \nIf the video/audio is longer than this value, only the content up to this duration will be downloaded."}},{"name":"video_quality","in":"query","required":false,"description":"Desired video quality. Available options:\n\n- `best`: Best available quality (default)\n\n- `1080p`: Full HD quality (1920x1080)\n\n- `720p`: HD quality (1280x720)\n\n- `480p`: SD quality (854x480)\n\n- `360p`: Low quality (640x360)\n    \n **Note:** If the video is **longer than 1 hour**, we automatically lower it to `720p`.","schema":{"type":"string","default":"best","description":"Desired video quality. Available options:\n\n- `best`: Best available quality (default)\n\n- `1080p`: Full HD quality (1920x1080)\n\n- `720p`: HD quality (1280x720)\n\n- `480p`: SD quality (854x480)\n\n- `360p`: Low quality (640x360)\n    \n **Note:** If the video is **longer than 1 hour**, we automatically lower it to `720p`."}},{"name":"video_format","in":"query","required":false,"description":"Desired output format for the video. Available options:\n\n- `mp4`: MP4 format (default option)\n\n- `webm`: WebM format\n\n- `mkv`: Matroska Video format\n\n**Note:** This is a format preference. While we will do our best to provide the requested format, \ndue to technical limitations or conversion issues, the final output format may differ from \nthe requested one.\nIn such cases, the video will be provided in the most compatible format available.","schema":{"type":"string","default":"mp4","description":"Desired output format for the video. Available options:\n\n- `mp4`: MP4 format (default option)\n\n- `webm`: WebM format\n\n- `mkv`: Matroska Video format\n\n**Note:** This is a format preference. While we will do our best to provide the requested format, \ndue to technical limitations or conversion issues, the final output format may differ from \nthe requested one.\nIn such cases, the video will be provided in the most compatible format available."}},{"name":"webhook_url","in":"query","required":false,"description":"URL of the webhook where results will be sent. When specified, the system will attempt to send the response \nto this URL up to 3 times with a 5-second delay between each attempt. The results will be sent as a POST request.\n\nThe payload will be sent in JSON format with one of the following structures:\n\nOn success:\n```json\n    {\n        \"id\": \"string\", // the job id,\n        \"status\": \"CompletedJob\", // the job status,\n        \"result\": {\n            \"metadata\": {\n                // filtered metadata object\n            },\n            \"response\": \"https://s3.huntapi.com/videos/video_id.mp4\"\n        }\n    }\n```\n\nOn error:\n\n```json\n    {\n        \"id\": \"string\", // the job id,\n        \"status\": \"Error\", // the job status,\n        \"error\": \"string\" // the error message (private, unavailable, age restricted, etc.)\n    }\n```","schema":{"type":"string","description":"URL of the webhook where results will be sent. When specified, the system will attempt to send the response \nto this URL up to 3 times with a 5-second delay between each attempt. The results will be sent as a POST request.\n\nThe payload will be sent in JSON format with one of the following structures:\n\nOn success:\n```json\n    {\n        \"id\": \"string\", // the job id,\n        \"status\": \"CompletedJob\", // the job status,\n        \"result\": {\n            \"metadata\": {\n                // filtered metadata object\n            },\n            \"response\": \"https://s3.huntapi.com/videos/video_id.mp4\"\n        }\n    }\n```\n\nOn error:\n\n```json\n    {\n        \"id\": \"string\", // the job id,\n        \"status\": \"Error\", // the job status,\n        \"error\": \"string\" // the error message (private, unavailable, age restricted, etc.)\n    }\n```"}},{"name":"webhook_authorization","in":"query","required":false,"description":"Authorization header for the webhook. This parameter allows you to add authentication to your webhook endpoint.\n    \nThis value will be included in the `Authorization` header when making the webhook request to your server.\n\nExample:\n    ```\n    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\n    ```","schema":{"type":"string","description":"Authorization header for the webhook. This parameter allows you to add authentication to your webhook endpoint.\n    \nThis value will be included in the `Authorization` header when making the webhook request to your server.\n\nExample:\n    ```\n    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\n    ```"}},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/is_async"},{"$ref":"#/components/parameters/soft_fail"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"}}},"examples":{"Example 1":{"value":{"job_id":"0193443f-fb80-9d19-29ba-82bc77c7cd84"}}}}}},"400":{"description":"Bad Request — missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad Request"}}}},"401":{"description":"Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid API Key"}},"planRateLimit":{"value":{"error":"Rate limit exceeded: You've exceeded the per second rate limit on your subscription"}},"keyQuota":{"value":{"error":"Rate limit exceeded for the API key: quota monthly"}}}}}},"402":{"description":"Payment Required — your subscription or credit balance is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Payment required"}}}},"500":{"description":"Internal Server Error — something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal Error"}}}}}},"post":{"summary":"Video Download","description":"**Credit cost:** 1 credit per call\n\n**Async:** This endpoint runs asynchronously. Use the jobs endpoint to poll for results.","operationId":"post-video-download","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/is_async"},{"$ref":"#/components/parameters/soft_fail"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Video URL to download.\n\n**Notes:**  Some videos cannot be downloaded for the following reasons:\n\n- **Private videos:** If the video is set as private by its owner\n\n- **Unavailable videos:** If the video has been deleted or is no longer accessible\n\n- **Age restricted videos:** If the video is age restricted. In these cases, the API will return an explanatory error message."},"download_type":{"type":"string","default":"audio_video","description":"Desired download type. You have three options:\n\n- `audio_video`: Downloads the complete video with audio (default option)\n\n- `audio`: Downloads only the audio track of the video (useful for extracting music or podcasts)\n\n- `video`: Downloads only the video part, without sound (ideal for visual content only)"},"max_duration":{"type":"number","description":"Maximum duration of the downloaded content in seconds.  \nIf the video/audio is longer than this value, only the content up to this duration will be downloaded."},"video_quality":{"type":"string","default":"best","description":"Desired video quality. Available options:\n\n- `best`: Best available quality (default)\n\n- `1080p`: Full HD quality (1920x1080)\n\n- `720p`: HD quality (1280x720)\n\n- `480p`: SD quality (854x480)\n\n- `360p`: Low quality (640x360)\n    \n **Note:** If the video is **longer than 1 hour**, we automatically lower it to `720p`."},"video_format":{"type":"string","default":"mp4","description":"Desired output format for the video. Available options:\n\n- `mp4`: MP4 format (default option)\n\n- `webm`: WebM format\n\n- `mkv`: Matroska Video format\n\n**Note:** This is a format preference. While we will do our best to provide the requested format, \ndue to technical limitations or conversion issues, the final output format may differ from \nthe requested one.\nIn such cases, the video will be provided in the most compatible format available."},"webhook_url":{"type":"string","description":"URL of the webhook where results will be sent. When specified, the system will attempt to send the response \nto this URL up to 3 times with a 5-second delay between each attempt. The results will be sent as a POST request.\n\nThe payload will be sent in JSON format with one of the following structures:\n\nOn success:\n```json\n    {\n        \"id\": \"string\", // the job id,\n        \"status\": \"CompletedJob\", // the job status,\n        \"result\": {\n            \"metadata\": {\n                // filtered metadata object\n            },\n            \"response\": \"https://s3.huntapi.com/videos/video_id.mp4\"\n        }\n    }\n```\n\nOn error:\n\n```json\n    {\n        \"id\": \"string\", // the job id,\n        \"status\": \"Error\", // the job status,\n        \"error\": \"string\" // the error message (private, unavailable, age restricted, etc.)\n    }\n```"},"webhook_authorization":{"type":"string","description":"Authorization header for the webhook. This parameter allows you to add authentication to your webhook endpoint.\n    \nThis value will be included in the `Authorization` header when making the webhook request to your server.\n\nExample:\n    ```\n    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\n    ```"}},"required":["query"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"}}},"examples":{"Example 1":{"value":{"job_id":"0193443f-fb80-9d19-29ba-82bc77c7cd84"}}}}}},"400":{"description":"Bad Request — missing or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad Request"}}}},"401":{"description":"Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"value":{"error":"Invalid API Key"}},"planRateLimit":{"value":{"error":"Rate limit exceeded: You've exceeded the per second rate limit on your subscription"}},"keyQuota":{"value":{"error":"Rate limit exceeded for the API key: quota monthly"}}}}}},"402":{"description":"Payment Required — your subscription or credit balance is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Payment required"}}}},"500":{"description":"Internal Server Error — something went wrong on our side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal Error"}}}}}}}},"components":{"parameters":{"fields":{"name":"fields","in":"query","required":false,"description":"Comma-separated list of response fields to return, with dot notation for nested fields (e.g. `name,location.city`).","schema":{"type":"string"}},"is_async":{"name":"is_async","in":"query","required":false,"description":"Run the request as a background job: the API answers `202` with a `job_id` to poll on `GET /v1/jobs/{id}`.","schema":{"type":"boolean","default":false}},"soft_fail":{"name":"soft_fail","in":"query","required":false,"description":"Return HTTP 200 even when the request fails; the error is in the `error` field of the body.","schema":{"type":"boolean","default":false}}},"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message."}}}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key. Include it in the x-api-key header for every request."}}}}