canonical: https://jentic.com/apis/huntapi.com/huntapi # HuntAPI API Reference The HuntAPI API downloads video and audio from media URLs on platforms such as YouTube, Instagram, TikTok, Vimeo, X, Facebook, Twitch, and Reddit, and reads their metadata without downloading the file. Video downloads choose a quality from 360p to 1080p or best, a format of mp4, webm, or mkv, and whether to keep the audio, the video, or both. Audio downloads output mp3, m4a, or wav at a chosen bitrate. Downloads run as asynchronous jobs that are polled for progress and result, or delivered to a webhook URL with an optional Authorization header. ## For AI agents Download video or audio from YouTube, TikTok, Instagram, Vimeo, and other media URLs as asynchronous jobs, or read a video's title, duration, channel, and view counts without downloading it. ## Scope Does not host, edit, or transcribe media. Use for reading media metadata and downloading video or audio from URLs only. ## Capabilities - Read a media URL's title, duration, thumbnail, channel, and view counts without downloading the file - Download a video at a chosen video_quality (best, 1080p, 720p, 480p, or 360p) as mp4, webm, or mkv - Extract only the audio track of a video, or only the silent video, with download_type - Download audio as mp3, m4a, or wav at best, 320kbps, 256kbps, or 128kbps quality - Cap a download's length with max_duration in seconds - Poll an asynchronous download job for status and progress, or receive the result at a webhook_url ## Use cases ### Agent media lookup through Jentic An AI agent handed a video link needs to know what it is before doing anything else. Through Jentic the agent searches for 'get metadata for a video URL', receives the HuntAPI Media Metadata operation with its input schema, and calls GET `/v1/media/metadata` with the URL as query. It reads the title, duration, channel, thumbnail, and view counts without downloading the file. Example prompt: Call GET `/v1/media/metadata` with query 'https://www.youtube.com/watch?v=dQw4w9WgXcQ' and report the title, duration, and channel ### Audio extraction for transcription A team transcribing interviews or talks needs the audio track only. GET `/v1/audio/download` takes the media URL as query, an audio_format of mp3, m4a, or wav, and an audio_quality, and returns a job id. Polling GET `/v1/jobs/{id}` until the status is CompletedJob gives the file to pass to a speech-to-text service. Example prompt: Call GET `/v1/audio/download` with query set to the talk URL, audio_format 'mp3', and audio_quality '128kbps', then poll GET `/v1/jobs/{id}` until status is CompletedJob and return the result ### Video archiving with webhooks A content team archives its own published videos across platforms. GET `/v1/video/download` takes video_quality, video_format, and download_type, and with webhook_url set the result is posted to that URL with up to three attempts. webhook_authorization adds an Authorization header so the receiving endpoint can check the request. Example prompt: Call GET `/v1/video/download` with query set to the video URL, video_quality '1080p', video_format 'mp4', and webhook_url 'https://example.com/hooks/huntapi' ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/v1/media/metadata` | Read metadata for a media URL | | GET | `/v1/video/download` | Start a video download job | | GET | `/v1/audio/download` | Start an audio download job | | GET | `/v1/jobs/{id}` | Poll a download job | | GET | `/v1/usage` | Usage and credit balance | ## Key resources - **Media metadata** — Title, duration, thumbnail, channel, and view counts for a media URL - **Video download** — Asynchronous video downloads with quality, format, and track options - **Audio download** — Asynchronous audio downloads in mp3, m4a, or wav - **Jobs** — Status, progress, and result of asynchronous downloads ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 55 / 100 - **Maturity:** Foundational - **Dimensions:** - Foundational Compliance: 72 / 100 - Developer Experience & Jentic Compatibility: 70 / 100 - AI-Readiness & Agent Experience: 33 / 100 - Agent Usability: 94 / 100 - Security: 50 / 100 - AI Discoverability: 56 / 100 - **View full report:** https://jentic.com/apis/huntapi.com/huntapi/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring HuntAPI by hand means sending the x-api-key header, starting a download job, and polling the jobs endpoint or running a webhook receiver for the result. Through Jentic you install once, import HuntAPI from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** HuntAPI puts each tool in its own URL path (`/v1/media/metadata`, `/v1/video/download`, `/v1/audio/download`), while the media URL travels as a query parameter. Rules bound which operations your agent may call, not which media links it uses, so you choose whether downloads are included at all. - **Credential handling:** Your HuntAPI key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'get metadata for a video URL' or 'download audio from a video', and Jentic returns the matching HuntAPI operation with its input schema so the agent sets the right quality and format fields without browsing the reference docs. ## Related APIs - **GetYouTubeTranscript API** — Fetches transcripts of YouTube videos - **AssemblyAI API** — Speech-to-text transcription and audio intelligence - **Deepgram API** — Speech recognition API for recorded and live audio - **Mux API** — Video hosting, encoding, and streaming ## FAQ ### What authentication does the HuntAPI API use? The HuntAPI API authenticates with an API key in the `x-api-key` request header, declared as the ApiKeyAuth scheme in its OpenAPI spec. The separate webhook_authorization parameter is not for HuntAPI itself: it sets the Authorization header HuntAPI sends to your webhook. Through Jentic the HuntAPI key is held by your own Jentic One instance and attached at call time. ### Which platforms does the HuntAPI API support? The spec lists YouTube, Instagram, TikTok, Vimeo, X, Facebook, Twitch, and Reddit as examples of supported media URLs. It notes that private, deleted, and age-restricted content may fail to download, so check GET `/v1/media/metadata` first if you are unsure. ### How do HuntAPI downloads return the file? Downloads are asynchronous. GET `/v1/video/download` and GET `/v1/audio/download` return a job id; poll GET `/v1/jobs/{id}` until the status is CompletedJob, Error, NotFound, or BadRequest, using progress (0 to 100) meanwhile. Alternatively pass webhook_url and the result is posted to your endpoint. ### What are the rate limits for the HuntAPI API? The OpenAPI spec does not specify rate limits; it describes credit costs and a GET `/v1/usage` endpoint for your balance. Check the HuntAPI documentation at https://huntapi.com for current limits. ### How do I download a video's audio through Jentic? Search Jentic for 'download audio from a video URL', load the GET `/v1/audio/download` operation, and execute it with query set to the URL and audio_format 'mp3'. Then poll GET `/v1/jobs/{id}` with the returned job id. To run it on your own infrastructure, install Jentic One from its GitHub repo. ### Is there a HuntAPI MCP server? You don't need an MCP server to give your agent HuntAPI. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls the metadata, download, and job operations on demand without extra tool definitions in its context. ### Can I limit what my agent is allowed to do with the HuntAPI API? Yes. For an agent that should only identify media, write a rule that allows GET `/v1/media/metadata` alone. It can then read titles, durations, and channels for links it is given, but it cannot start video or audio downloads, and every call it makes is logged.