Openhandle API versioning and deprecation

The public REST API uses URL versioning: current operations start with /v1/. The info.version field in OpenAPI identifies the document release. It does not select a different API version.

Compatibility

Breaking contract changes use a new major URL version. Examples include removing a documented field or changing its type. Clients should ignore unknown response fields so additive fields can be introduced within a major version. Additional endpoints can also be introduced without changing existing endpoints.

Source platforms can change availability or stop exposing data. A platform failure or an unknown metric is not an API version change. Continue handling the documented error codes and nullable metrics.

Contract change notices

Each notice names the contract version that carries the change, what changed, and how to update a reader.

1.2.9: YouTube storyboards and frames

GET /v1/youtube/posts/{identifier}/storyboard returns YouTube's preview frames of a video: one small frame every few seconds, packed into image sheets, with the position of every frame. GET /v1/youtube/posts/{identifier}/frame returns one still frame at a time in seconds, set with the required at parameter. resource can now be storyboard or frame. Nothing else changes. If you switch on resource, add both.

1.2.8: YouTube video files

GET /v1/youtube/posts/{identifier}/files returns the video and audio streams of a YouTube video as download links. resource can now be files. The links are Openhandle media links, so they keep working after YouTube's own links expire. Nothing else changes. If you switch on resource, add files.

1.2.7: YouTube

YouTube joins as a fifth platform with 26 endpoints under /v1/youtube. See YouTube. platform can now be youtube, and resource can be playlist, transcript, product, or chart. Page metadata gains comments, estimatedResults, playlist, hashtag, chartWeek, country, and category on YouTube answers. Nothing changes for the other platforms. If you switch on platform or resource, add the new values.

1.2.6: Instagram story and highlight resources

Instagram story answers now carry resource: "story", and highlight answers carry resource: "highlight". Both used resource: "entity" before. This applies to GET /v1/instagram/stories/{identifier}, GET /v1/instagram/highlights/{identifier}, the profile stories and highlights lists, and POST /v1/urls/fetch. The data shapes do not change. If you branch on resource, match the new values.

1.2.4: Instagram caption details

An Instagram post's caption is an InstagramCaptionReference, not a comment. It keeps id, createdAt, status, isCovered, isEdited, sharingEnabled, ranking.isRanked, and translation.text. The comment keys text, author, metrics, replies, and the other comment-only keys are no longer present on it. Read the caption text from the post's text, which is unchanged.

1.2.2: Error codes, list shapes, and search options

• A missing post answers POST_NOT_FOUND and a missing comment answers COMMENT_NOT_FOUND. A missing hashtag, location, music, playlist, subreddit, or other resource answers RESOURCE_NOT_FOUND. Profiles still answer PROFILE_NOT_FOUND.
• A page token the provider no longer accepts answers UPSTREAM_SWITCHED with HTTP 409. Restart the pagination from the first page.
• A sort, type, or other option the endpoint does not accept answers INVALID_PARAMETER. type is required on Twitter media search.
• Instagram hashtag and location posts return recent posts unless you send sort=top. Twitter post search returns the latest posts unless you send sort=top.
• Instagram suggested profiles and TikTok trending music are lists with a cursor, as the API always answered. Reddit post comments, rules, trophies, moderated subreddits, and wiki pages are lists without a cursor.

1.2.1: TikTok media types

TikTok media files are typed by kind: TikTokMedia, TikTokImage, TikTokRendition, TikTokSubtitle, and TikTokAudio replace the single TikTokAsset. Mirror addresses move from variants[].url to urls[], and avatar sizes move from variants[] to renditions[]. Video-only keys are no longer present on pictures. See the TikTok media section for the full mapping. Other platforms are unchanged.

Deprecation and retirement

Version 1 has no announced retirement date. A deprecation notice will identify the affected version or operations, a replacement, migration steps, and any scheduled retirement date in this documentation. Deprecation means an operation is discouraged; sunset means it is scheduled to stop responding.

No fixed minimum notice period is currently promised. Review the published notice for the affected operation before planning a migration. Contact hello@openhandle.dev with compatibility questions.

For automated monitoring, the standards define Deprecation as a Structured Field date and Sunset as an HTTP date. A Link with rel="deprecation" can identify migration documentation. These headers are only relevant when a resource has an actual deprecation or retirement announcement. Active v1 operations do not emit artificial retirement dates.

See RFC 9745 and RFC 8594 for the header formats.