Migration Guide: API v1 to API 2026-01

Overview of Changes

The 2026-01 API introduces several breaking changes. The most significant are the switch from camelCase to snake_case in response property names and the rename from "projects" to "folders" throughout the API.

API Versioning

Path-Based Versioning (v1)

Originally we wanted to use path based versioning for our API. The v1 version of the API reflects this. To request the v1 version, no special headers are needed, just prefix the path with v1:

https://api.wistia.com/v1/medias
https://api.wistia.com/v1/projects/abc123

Modern API with Header-Based Versioning

The modern API replaces the version in the path with /modern and uses the X-Wistia-Api-Version header to specify stable release versions:

# Stable 2026-01 release via header
curl https://api.wistia.com/modern/medias \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "X-Wistia-Api-Version: 2026-01"

In the above version we are requesting the 2026-01 release of the API. If you request a date that doesn't have a corresponding release, you will be served the version that comes before that date. For example, requesting 2026-02 would get you the 2026-01 version of the API if nothing was released in February.

If you request a deprecated version, you will get the least recent stable release. For example, if you request 2025-11 (this is an example version, it never was released) you would get 2026-01 if it was still supported.

You can also omit the API version. Doing this will get you the most recent stable release. It is generally safer though to always set the X-Wistia-Api-Version. If you are just starting building a feature around our API, a best practice would be to set X-Wistia-Api-Version to the most recent release so you get the latest features and stability as we release future versions.

Version Stability Guarantees

v1 (/v1/*): Evergreen version with no breaking changes. Stable but will never be updated with new features. This version is only recommended for existing users of this API.
Stable releases (/modern/* with X-Wistia-Api-Version header): Timestamped stable releases (e.g., 2026-01) that guarantee no breaking changes until the older version is deprecated.

Stable releases in the modern API will be supported up to a year from their release date. For example, the 2026-01 release will be supported until 2027-01. Once a version is deprecated, requesting it will give you the least recent stable release. For example, if 2026-03 was still supported and you requested 2026-01 you would get the 2026-03 version to minimize the amount of breaking changes that would happen.

Breaking Changes

Response Property Names Changed from camelCase to snake_case

Most response objects now use snake_case property names instead of camelCase.

API v1 Project response (camelCase):

{
  "id": 123,
  "hashedId": "abc123",
  "mediaCount": 5,
  "anonymousCanUpload": false,
  "anonymousCanDownload": false
}

API 2026-01 Folder response (snake_case):

{
  "id": 123,
  "hashed_id": "abc123",
  "media_count": 5,
  "anonymous_can_upload": false,
  "anonymous_can_download": false
}

Projects Renamed to Folders

The projects resource has been renamed to folders. This affects multiple areas of the API:

Data API Endpoints

/projects → /folders
/projects/{projectId}/sharings → /folders/{folderId}/sharings

Note: The Stats API path /stats/projects/{projectId} was not renamed. It remains /stats/projects/{projectId} in 2026-01.

Response Objects

All media responses that previously included a project field now include a folder field instead:

API v1:

{
  "id": 123,
  "hashed_id": "abc123",
  "name": "My Video",
  "project": {
    "id": 456,
    "name": "Marketing Videos",
    "hashed_id": "xyz789"
  }
}

API 2026-01:

{
  "id": 123,
  "hashed_id": "abc123",
  "name": "My Video",
  "folder": {
    "id": 456,
    "name": "Marketing Videos",
    "hashed_id": "xyz789"
  }
}

`project_id` Parameter Renamed to `folder_id`

The project_id parameter has been renamed to folder_id wherever it appears. This affects the media list query parameter as well as the request body for the media copy and media move endpoints.

Media list — API v1:

GET /v1/medias?project_id=xyz789

Media list — API 2026-01:

GET /modern/medias?folder_id=xyz789

Media copy / move request body — API v1:

{ "project_id": "xyz789" }

Media copy / move request body — API 2026-01:

{ "folder_id": "xyz789" }

Singular hashed_id Parameter Removed

The singular hashed_id query parameter has been removed. Use the plural hashed_ids[] parameter instead:

API v1:

GET /v1/medias?hashed_id=abc123

API 2026-01:

GET /modern/medias?hashed_ids[]=abc123

Live Stream Events Renamed to Webinars

Resources related to live streaming have been renamed webinars:

/v1/live_stream_events → /modern/webinars
/v1/live_stream_event_registrations → /modern/webinar_registrations

New Features

Bulk Copy Media

A new /modern/medias/copy endpoint allows copying multiple medias to a destination folder in a single request:

PUT /modern/medias/copy
{
  "hashed_ids": ["abc123", "def456", "ghi789"],
  "folder_id": "xyz789"
}

This endpoint processes requests asynchronously and returns a background_job_status object.

Bulk Taggings

A new POST /modern/taggings/bulk_create endpoint allows adding tags to multiple medias in a single request:

POST /modern/taggings/bulk_create
{
  "hashed_ids": ["abc123", "def456"],
  "tag_names": ["marketing", "demo"]
}

Channel Management Endpoints

Channels now support full CRUD operations. The following endpoints are new in 2026-01:

POST /modern/channels — Create a channel
PUT /modern/channels/{channel_hashed_id} — Update a channel
DELETE /modern/channels/{channel_hashed_id} — Delete a channel

Channel Episode Endpoints

New endpoints for managing channel episodes:

PUT /modern/channel_episodes/{channel_episode_hashed_id} — Update a channel episode
DELETE /modern/channel_episodes/{channel_episode_hashed_id} — Delete a channel episode
PUT /modern/channel_episodes/{channel_episode_hashed_id}/publish — Publish a channel episode
PUT /modern/channel_episodes/{channel_episode_hashed_id}/unpublish — Unpublish a channel episode

Cursor-Based Pagination

List endpoints for folders, channels, channel episodes, folder sharings, and subfolders now include a cursor field in their response objects. This can be used for cursor-based pagination in addition to offset-based pagination.

Subfolder Bulk Delete

A new endpoint for deleting multiple subfolders at once:

DELETE /modern/folders/{folder_id}/subfolders/bulk_delete