Wistia API Guide: Data, Upload, Stats, Webhooks and the MCP Server

Wistia gives developers six ways in: a versioned Data API at api.wistia.com/modern, an Upload API, a Stats API, a JavaScript Player API, webhooks and an MCP server for AI agents. Every REST request carries a Bearer token and an X-Wistia-API-Version header (the default is 2026-09), and the whole account shares one limit of 600 requests per minute. Two gates matter more than any endpoint. Only the Account Owner can create API tokens, and the MCP server works only for owners and managers. Plan features also carry through: a webinar endpoint answers 403 on a plan without webinars.

Six surfaces, one account

The Data API manages the library as JSON over HTTP: media, folders, tags, captions, dubs, channels, webinars, brands and player customizations. Uploads, stats, the browser player, webhooks and the MCP server each have their own surface, and Wistia ships an official TypeScript SDK, @wistia/wistia-api-client, plus a CLI built from the same API. One design note shapes the rest. The APIs were built for videos in folders, and Wistia does not formally support them for audio files or audio episodes in Channels, so podcast-heavy accounts should confirm their use case first.

Tokens, roles and OAuth

Access starts in Account Settings, on the API tab. Only the Account Owner can create, view and manage tokens, and a token can be copied once, at creation; tokens created since 14 June 2024 are hashed and never stored in plain text. Permissions stay editable afterward. Each token carries scopes such as Read all data, Read detailed stats, Upload, or Read, update and delete anything. A delegate scope lets a token act with a chosen team member's permissions, so a script sees only what that person could see. Send it as a Bearer header everywhere; query-parameter authentication was deprecated on 30 July 2022.

Expiring tokens cover the browser cases, such as site visitors uploading files. They last two days by default, can only be minted from a permanent token, and can name specific media, folders, channels or webinars with permissions like view-stats, share or upload. The catch: Wistia marks this API as still under development and subject to change, and expiring tokens with authorizations cannot call search, bulk actions, the account endpoint or the credit balance. Each of those answers 403.

OAuth exists for third-party apps but is not on by default. You request it from Wistia; scopes are all:all, all:read, media:read, stats:read and media:upload, only Managers and owners can authorize an app, and the sample access token lasts six hours with a refresh token behind it. Changing an app's permissions does not update tokens already issued. Users must authorize again.

Versions, rate limits and paging

Versioning is date-based and lives in a header. The current spec is 2026.09.0, and every Data API and Stats API request sends X-Wistia-API-Version, with 2026-09 as the documented default. The 2026-01 stable release brought snake_case responses, renamed projects to folders and renamed live stream events to webinars; a migration guide covers accounts still on V1 ^[1]. The rename is not universal. The Stats and Upload APIs keep project naming, so upload calls still send project_id, and channel endpoints exist only on the modern API.

The rate limit is 600 requests per minute per account, counting only calls to upload.wistia.com and api.wistia.com, and a breach returns HTTP 429 with a Retry-After header ^[2]. Some endpoints throttle harder. Move Media allows 10 requests per 5 minutes and 100 items per call, while the bulk endpoint escapes both limits but cannot create media. Restores accept up to 1,000 hashed IDs at once. Long jobs such as archive, copy, swap and translate return a background job to poll.

Paging and retention set the rest of the ceiling. List endpoints cap per_page at 100, form conversions use cursor paging with 25 results by default, and the Stats API returns viewing events only from the past two years, the standard retention period. Analytics date ranges cannot exceed two years either, and percentages come back rounded to whole numbers. Webinar aggregates appear only after the event ends; before that the endpoint answers 409.

Uploads have their own rules. A URL import needs the right file extension, such as .mp4, and presigned links should stay valid for a few hours because processing can queue. Files sent without a folder land in an auto-created folder named for the upload date, and the Upload API cannot target subfolders. Bulk migrations should set the low_priority flag. Accounts with a hard storage or video limit see uploads blocked with a named reason.

The player in the page, and webhooks behind it

Browser code depends on which player you embed, a split our Wistia embed guide covers in full. The Aurora player is a web component with its own JavaScript API and npm packages for plain JavaScript and React. It does not use window._wq; base options go through window.wistiaOptions. The legacy Vulcan player still works through E-v1.js, where you push onReady callbacks onto window._wq or call Wistia.api with a matcher, and a revoke key stops duplicate callbacks when single-page-app components remount.

Useful methods include secondsWatchedVector, which returns how often each second was watched, W.consent for per-visitor privacy, and show and hide for popovers. Aurora can be pinned to a version, but a pinned player stops getting bug fixes and security patches. The iframe embed is the trap. It still plays, yet it loses the JavaScript Player API, domain restrictions and the HubSpot, Marketo and Pardot hooks, although Aurora's Plugin API works inside iframes. Self-hosting E-v1.js is unsupported.

Webhooks are configured in Account Settings and arrive as a JSON POST signed with an X-Wistia-Signature header, a SHA-256 HMAC of the body under your secret. Events cover the media lifecycle (created, ready, failed, transcript updated, dub created), viewing sessions, form conversions and webinar registrations with UTM data. Percent-watched events fire at 25, 50, 75 and 100 percent, and carry name and email only when the session included a Wistia Form submission. Delivery is at least once, unordered and batched. Dedupe on the event uuid and answer within the 10-second timeout.

The MCP server and the CLI

The MCP server, announced in July 2026, sits at api.wistia.com/mcp/api and accepts OAuth or an access token ^[3]. It is limited to account owners and managers. Through it an agent can upload or import a video by URL, trim and swap media, manage webinars, create channels and publish episodes, and compare stats across videos or over time. Anything it cannot do yet comes back as steps and a link for doing it in the app.

Setup differs by client. Claude asks for approval on every action by default, adjustable per tool, and Claude Code adds the server over the http transport with a Bearer header. ChatGPT supports OAuth only, through Wistia's official app or a custom connector in Developer mode on the web. By default every tool is exposed. A toolsets parameter narrows the list to any of 12 groups, from media and folders to stats, sharing, Remix and account, and an unknown name returns 422. For terminals and CI jobs, the CLI runs on macOS, Linux and Windows and prints JSON, YAML or tables.

Plan gates and what API work costs

The API does not bypass plans. A valid token on an account without a feature gets 403, and the documented example is webinars, which need a Webinars plan at $429 a month billed annually or above. Ordering extended audio descriptions through the API needs a paid plan, buying English captions charges the saved credit card, and dubs created through the API bill per minute once the free allowance is gone. The Account Usage endpoint shows owners and managers their storage, seat and bandwidth limits, flexible or hard. Its tier values still include legacy plans, because the plans changed in March 2026.

Engagement sync into HubSpot, Marketo or Pardot is Signals, not the API; see Wistia pricing for what that tier adds. For an app that only needs hosting and playback, Wistia offers a usage-priced Developer plan: free to 25 GB of storage and 200 GB of bandwidth a month, then a $25 platform fee on top of usage ^[4]. Storage beyond that runs $0.05 per GB and bandwidth $0.08 per GB in the first tiers, billed at month end, with documentation instead of an account manager for support.

Run the numbers before choosing. A library of 100 GB with 500 GB delivered a month costs $3.75 for storage, $24 for bandwidth and the $25 fee, or $52.75 a month by our arithmetic. At 250 GB stored and 1 TB delivered, counting 1 TB as 1,000 GB, the bill reaches $11.25 plus $64 plus $25, or $100.25 a month. That is above Business at $79 a month billed annually and slightly above its $99 monthly price. Small, quiet libraries favor usage pricing. Busy ones do not. Compare features on the plan page too, since this math covers storage and bandwidth only.

The bottom line

The Wistia API is broad and current: a dated version header, a typed SDK, signed webhooks, a CLI and an MCP server that lets an agent run the library. Plan around the gates rather than the endpoints. The Account Owner holds every token, the MCP server needs an owner or manager, 600 requests a minute is the shared ceiling, and plan features still decide what answers 403. Teams pulling stats into their own dashboards or automating uploads will find what they need. Teams that want engagement inside their marketing platform need Signals as well.