YouTube Content ID API - Revision History

  • The YouTube Content ID API is exclusively for YouTube content partners, not for general developers or users.

  • Significant updates to the API have been made, such as the videoAdvertisingOption.adFormats[] field now solely supporting third_party, and the deprecation of various advertising option fields, all reflecting in the latest update as of November 10, 2023.

  • Multiple resource and method updates have been implemented, including enhancements to claim searching, asset data retrieval, metadata handling, and ownership management.

  • The API now uses 22-character IDs for content owners instead of Partner Codes and has introduced asset labels for better asset categorization.

  • The API documentation provides comprehensive details on error handling, with numerous new error types added across various methods to help with troubleshooting.

Note: The YouTube Content ID API is intended for use by YouTube content partners and is not accessible to all developers or to all YouTube users. If you do not see the YouTube Content ID API as one of the services listed in the Google API Console, see the YouTube Help Center to learn more about the YouTube Partner Program.

This page lists YouTube Content ID API changes and documentation updates.

March 26, 2025

Starting March 31, 2025, YouTube will change how views for Shorts are counted. In the past, for Shorts, a view was counted after a Short was played for a certain number of seconds. Now, views will count the number of times your Short starts to play or replay, with no minimum watch time requirement. Learn more

By June 30, 2025, the Content ID API will be updated in the following ways as per this change:

  • claimSearch.list.sort will have its sort orders updated:
    • DAILY_ENGAGED_VIEWS will be added for daily view counts based on the previous view counting methodology.
    • LIFETIME_ENGAGED_VIEWS will be added to lifetime view counts based on the previous view counting methodology.
  • assetSearch.list.sort will have its sort orders updated:
    • DAILY_ENGAGED_VIEWS will be added for daily view counts based on the previous view counting methodology.

By September 30, 2025, the Content ID API will be updated in the following ways as per this change:

  • assetSearch.list.sort sort order VIEWS will be deprecated.
  • claimSearch.list.sort sort order VIEW_COUNT will be deprecated.
  • claimSearch.claimSnippet.videoViews will be updated to reflect the updated view count methodology for views for Shorts.
  • claimSearch.claimSnippet.engagedViews will be added for view counts based on the previous view counting methodology

January 14, 2025

The videoAdvertisingOption resource's autoGeneratedBreaks[] field has been updated as now we allow ad_breaks and autoGeneratedBreaks to be provided at the same time. If autoGeneratedBreaks is set to true on a video with adBreaks defined, our systems will identify places to show ads in addition to your manually placed ad slots. See support article for more details.

November 10, 2023

The videoAdvertisingOption resource's adFormats[] field has been updated so that third_party is the only valid value for that field. The following ad formats are no longer supported: instream_trueview, instream_standard, display, preroll, postroll. See support article for more details.

June 1, 2023

Note: This is a deprecation announcement.

This update includes the following changes:

December 20, 2022

The definition of the assetSearch.list method's ownershipRestriction query parameter has been updated to clarify that if that parameter's value is none, the metadataSearchFields parameter value must also use at least one ID filter. This documentation change does not reflect a change in API behavior.

November 9, 2022

The documentation for the asset.get and asset.list methods has been updated to clarify how multiple values are supported for:

September 28, 2022

Licensability information has been added to the asset resource.

July 18, 2022

The documentation for the claimSearch.list method's inactiveReasons has been updated to reflect improvements for consistency with YouTube Studio:

  • Studio had previously removed support for Audio Swap and Song Erase. The corresponding API values, audio_removed and song_erased, were silently ignored and have now been undocumented.
  • channel_whitelisted has been replaced with channel_allowlisted. The previous value is no longer documented but is still supported.
  • The values closed_disabled_monetization, closed_manually, closed_no_adsense, closed_own_video_match, reference_removed, replaced, and video_modified are now supported.

June 14, 2022

The assetSearch resource documentation has been updated to reflect the two new properties: isrcs[] and iswcs[]. The new isrcs[] and iswcs[] property values each contain an array of string values with each value specifying an ISRC or ISWC, as appropriate, that maps to the asset identified by the search result.

The new properties are recommended over the isrc and iswc properties already included in assetSearch resources because the new properties provide more accurate data. Whereas the new properties potentially list an array of string values, the isrc and iswc properties each identify only one ISRC or ISWC code associated with the search result.

May 12, 2022

The links to client libraries were updated to point to the standard Google APIs client libraries. Pre-generated bindings for PHP were updated.

May 3, 2022

The claimSearch.list method's status parameter now supports more filters based on potential claim details.

May 2, 2022

The documentation for the assetSearch.list method's Response has been updated to reflect improvements for consistency with AIP-158:

  • The description of pageInfo.totalResults explicitly mentions that the value is an estimate and not the actual value
  • Fields pageInfo.resultsPerPage and pageInfo.startIndex have been removed

April 25, 2022

The documentation for the assetLabels.list resource has been updated to clarify the meaning of labelPrefix and q request parameters, and to document that the request / response support pagination.

December 8, 2021

The documentation for the claimSearch.list resource has been updated to properly reflect the two use cases this method covers:

  • Search by ID (asset, reference or video) or query string
  • Search by claim creation date, modification date, or status

Each use case supports a different set of query parameters. The claimSearch.list method's documentation has been updated to explain which parameters are supported for each use case.

November 17, 2021

This update includes the following changes:

  • The claims.update method now supports the ability to update an inactive or potential claim's status to active. The definition of the claim resource's status property provides more details.
  • The documentation for the claim and claimSearch resources has been updated to reflect the addition of the new studioInfo object, which contains links to YouTube Studio pages related to the claim.
  • The list of values supported for the claimSearch.list method's origin parameter has changed. The parameter now supports four additional values: batchTool, inProductShorts, melodyMatch, and youTubeAdmin. In addition, the dropboxUpload and webUpload values are no longer supported.

February 26, 2021

The documentation for the claimSearch.list method's videoId parameter has been updated to note that the parameter value now accepts a maximum of 10 comma-separated video IDs. The API will return a badRequest error — 400 HTTP response code — if the value contains more than 10 video IDs.

December 6, 2018

Note: This is a deprecation announcement.

The API documentation has been updated to remove references to the contentOwnerAdvertisingOptions resource and its methods. These methods were very minimally used, and API users that did use them have been contacted separately prior to this announcement.

March 21, 2018

This update contains the following changes:

  • The metadataMine.artist property must now be set any time you insert, update, or patch a music video or sound recording asset. The API now returns an error if the property is not set for those resource types. In addition, note that the metadataMine.artist property is only supported for music video and sound recording artists.

July 24, 2017

This update contains the following changes:

  • The new package resource represents a group of files delivered via the web, SFTP, or another delivery mechanism. The API's supports two methods for this resource:

    • The package.insert method validates and uploads a metadata-only package containing exactly one metadata file.
    • The package.get method retrieves information about a previously uploaded package.

  • For the validator.validate method, the definition of the uploaderName property has been updated to note that the value does not identify the content partner uploading the data but rather a value like web-google or yt-google that identifies the specific uploader account that the content owner is using.

  • The reference resource's status property no longer uses the value duplicate_on_hold to indicate that a reference is a duplicate of another reference. Instead, if a reference is a duplicate, the value of the status property is now set to inactive, and the value of the statusReason property is REASON_DUPLICATE_FOR_OWNERS.

    However, as before, the resource's duplicateLeader property is only populated if the reference is a duplicate. If it is set, then that property's value identifies the duplicated reference.

April 17, 2017

This update contains the following changes:

  • The new assetShare resource which is only relevant to composition assets, identifies a relationship between two representations of an asset resource. These representations reflect a new publishing data model designed to provide more transparency into and control over how your rights are associated with sound recording assets.

    In the new model, each sound recording maps to exactly one, unique asset, which is called a composition view. That asset's metadata represents the canonical set of information that YouTube displays about the composition rights associated with a given recording, and it may synthesize information from multiple data providers.

    In addition, each owner of the composition has its own composition share asset. The composition share represents the information that a particular publisher provided for a composition asset. The composition share can be associated with many sound recordings.

    The assetShare resource identifies a relationship between a composition view and a composition share. The new assetShares.list method lets you do either of the following:

    • Provide the ID of a composition view and retrieve the corresponding composition share owned by the partner authorizing the request, if such a share exists.
    • Provide the ID of a composition share owned by the content partner and retrieve a list of all of the composition views to which that share is linked.

  • The new Managing composition assets guide explains how different API methods handle requests depending on whether the asset IDs submitted to those methods identify composition views or composition shares.

  • The contentOwnerAdvertisingOptions resource's new claimedVideoOptions.autoGeneratedBreaks property indicates whether YouTube should automatically generate ad breaks in claimed videos that are more than 10 minutes long. While the property affects all of the content owner's videos that are more than 10 minutes long, if a video has multiple claims, the first partner that claims a video sets the default behavior for this property in relation to that video.

August 11, 2016

This update contains the following changes:

  • The newly published YouTube API Services Terms of Service ("the Updated Terms"), discussed in detail on the YouTube Engineering and Developers Blog, provides a rich set of updates to the current Terms of Service. In addition to the Updated Terms, which will go into effect as of February 10, 2017, this update includes several supporting documents to help explain the policies that developers must follow.

    The full set of new documents is described in the revision history for the Updated Terms. In addition, future changes to the Updated Terms or to those supporting documents will also be explained in that revision history. You can subscribe to an RSS feed listing changes in that revision history from a link in that document.

May 31, 2016

This update contains the following changes:

  • New resources and methods

    • The new validator.validate method lets you determine whether a metadata file contains validation errors that would prevent YouTube from processing it successfully. If the file contains errors, the API response's errors property contains a list of validation errors, identifying the severity, cause, and location of each error.

  • New and updated errors

    • The assets.patch and assets.update methods now support the following error. As a reminder, a method can support multiple errors that have the same error type. Please refer to the error documentation for each method or to the errors page for a complete list of possible errors.

      Errors
      invalidValue (400) parameters.assetId
      The request failed because the asset being updated has been merged with another asset. Resubmit the request using that asset's ID, which is returned in the error message, as the value of the assetId parameter.

March 28, 2016

This update contains the following changes:

  • Updates to existing resources and methods

    • The claim resource's new matchInfo.matchSegments[] property contains a list in which each item describes a segment of the claimed video that matches part of the reference video. A claim can have multiple match segments. For example, if the audio and video content of an uploaded video match that of a reference video, there would be two match segments. One segment would describe the audio match and the other would describe the video match.

      For each match segment, the API returns the duration and type (audio or video) of the matched content. The API also identifies the time offsets at which each match segment begins and ends in both the claimed video and the reference video.

    • The contentOwnerAdvertisingOptions resource's claimedVideoOptions.newVideoDefaults[] property value can now be updated when you call the contentOwnerAdvertisingOptions.patch or contentOwnerAdvertisingOptions.update methods.

    • The contentOwnerAdvertisingOptions resource's read-only allowedOptions.autoGeneratedBreaks property has been deprecated.

  • New and updated errors

    • The API's claims.update method now supports the following error. As a reminder, a method can support multiple errors that have the same error type. Please refer to the error documentation for each method or to the errors page for a complete list of possible errors.

      Errors
      badRequest (400) alreadyClaimed
      The claim is a duplicate of another existing claim and cannot be updated.

    • The assets.list method occassionally times out and returns a 500 HTTP response code (Internal Server Error), notably when the request retrieves data for many assets and the value of the fetchMatchPolicy parameter is effective. If your assets.list request specifies multiple asset IDs and returns a 500 error, try resubmitting the request for a single asset or a smaller number of assets.

    • The references.insert error documentation has been updated to note that if the request uploads a corrupted reference file, that issue is not identified until the reference itself is processed. So, even if the references.insert request returns a successful response, the reference might not be processed successfully. We recommend that, after inserting a reference, you poll using the references.list method to confirm that the reference is activated as expected.

February 3, 2016

This update contains the following changes:

  • Updates to existing resources and methods

    • The API now supports product listing ads. Product listing ads highlight products that are related to or are featured in a video's content. These ads are sponsored cards that display during the video. The cards are added automatically by the ad system. Viewers see a teaser for the card for a few seconds and can also click the icon in the top right corner of the video to browse the video's cards.

      As a result of this change, product_listing can now be included in the following properties' values:

      Resource/API method Property
      contentOwnerAdvertisingOptions allowedOptions.licAdFormats[]
      contentOwnerAdvertisingOptions allowedOptions.ugcAdFormats[]
      contentOwnerAdvertisingOptions claimedVideoOptions.newVideoDefaults[]
      videoAdvertisingOptions adFormats[]
      videoAdvertisingOptions.getEnabledAds countriesRestriction[].adFormats[]

    • The assetSearch.list method's new createdBefore and createdAfter instruct the API to only return assets created before and/or after a certain date.

    • In the API response to an assetSearch.list request, the type property now supports the value art_track_video. The YouTube Help Center provides more information about art track videos.

    • The claimSearch.list method supports the following new parameters:

      Parameters
      referenceId This filter parameter specifies the YouTube reference ID of the reference for which you are retrieving claims.
      inactiveReasons This optional parameter lets you restrict the API response to only include inactive claims based on specified reasons why the claims became inactive. The parameter definition lists the types of inactive claims for which you can search.
      partnerUploaded This optional Boolean parameter lets you specify that the API response should only include either partner-uploaded or non-partner-uploaded claims.

    • The reference resource's new references#origination object contains information that describes the source of the reference.

    • The references.insert method now supports the ability to upload references generated using YouTube's gfp_gen software. If you provide a pre-generated fingerprint, set the fpDirect property value to true in the uploaded reference resource.

      Note that with this change, the API no longer returns an error if you try to set the fpDirect property when uploading a reference.

  • New and updated errors

    The documentation now lists errors returned by the whitelist resource's methods.

    In addition, the following table identifies new errors that the API supports and the methods that could return each error. Note that a method may return multiple errors that have the same error type. Please refer to the error documentation for each method or to the errors page for more information.

    Errors
    badRequest (400) inappropriateCampaignTarget
    The campaigns.insert and campaigns.update methods return this error if a campaign attempts to feature a video that may be inappropriate for some users. To address the error, please choose different content to feature.
    badRequest (400) canNotCreatePartnerUploadedClaimOnCompositionOrSoundRecordingAssets
    The claims.insert method returns this error if you try to create a partner-uploaded claim with a composition or sound recording asset.
    badRequest (400) existingSoundRecordingOrMusicVideoClaim
    The claims.insert method returns this error if a claim already exists for recorded music on the specified video. Direct composition claims cannot be added via the API.
    badRequest (400) asset_id
    The references.insert method returns this error if the request attempted to create a reference through a file but the request did not specify an assetId.
    badRequest (400) canNotBeActivated
    The references.update method returns this error if the reference cannot be activated, possibly due to the reference's status or to ownership conditions.
    badRequest (400) videoNotClaimed
    The videoAdvertisingOptions.get method returns this error if you have not claimed the video for which you you are trying to retrieve advertising options, thereby making the requested information unavailable to you.

December 18, 2015

European Union (EU) laws require that certain disclosures must be given to and consents obtained from end users in the EU. Therefore, for end users in the European Union, you must comply with the EU User Consent Policy. We have added a notice of this requirement in our YouTube API Terms of Service.

April 21, 2015

This update contains the following changes:

March 30, 2015

This update contains the following changes:

  • Updates to existing resources and methods

    • The assetSearch.list method's new isrcs parameter lets you specify a list of up to 50 ISRCs. The API response will include assets associated with those ISRCs.

    • The claimHistory resource's event[].reason property supports the following new values. Each reason explains why a particular event related to the claim occurred:

      • closed_audio_claim_on_visual_reference
      • closed_partner_exclusion
      • closed_reference_conflict

    • The claimSearch.list method's new sort parameter specifies the method that will be used to order resources in the API response. By default, resources are sorted in reverse chronological order (from newest to oldest) based on the dates they were created. You can also sort resources from highest to lowest number of views for the claimed content.

      Note that if the claimSearch.list request also sets the status parameter value to either appealed, disputed, pending, potential, or routedForReview, then results are sorted by the time that the claim review period expires.

    • The ownership.update and ownership.patch methods now correctly list all of the properties that can be updated when calling these methods. This change represents a correction to the API documentation and does not identify a change to API functionality.

    • The fetchMatchPolicy parameters for the assets.get and assets.list methods now list effective as a supported value. The value instructs the API server to retrieve the match policy that YouTube applies for the asset.

    • The id parameters for the assets.list, claims.list, contentOwners.list, policies.list, publishers.list, and references.list methods all now note that their parameter values can contain a maximum of 50 comma-separated IDs.

  • New and updated errors

    The table below identifies new errors that the API supports and the methods that could return each error. Note that a method may return multiple errors that have the same error type.

    Please refer to the error documentation for each method or to the errors page for more information.

    Error type Error detail Description
    badRequest (400) tooManyIsrcs The assetSearch.list method returns this error if the isrcs parameter specifies more than 50 ISRCs.
    badRequest (400) videoIsPrivate The claims.insert method returns this error if you try to claim a private video. You can only claim a video if its privacy status is public or unlisted.
    notModified (304) blockOutsideOwnershipUnchanged The claims.update method returns this error if the blockOutsideOwnership flag on the claim was not successfully modified. There are several reasons why this error might occur. A common example is because the specified modification has no effect on the claimed video.

November 7, 2014

This update contains the following changes:

  • Updates to existing resources and methods

    • The claimSearch.list method's status parameter now supports a value of routedForReview. This value restricts results to claims that require manual review based on a rule in an asset's match policy.

    • The claimHistory resource's event[].reason property supports the following new values. Each reason explains why a particular event related to the claim occurred:

      • closed_invalid_reference_segment
      • closed_noadsense
      • suspended_monetization_on_channel
      • video_content_modified

    • The claim resource's origin.source property, which identifies the source of a claim, now supports the value melodyMatch. A melody match claim indicates that the claimed video shares a musical composition with a reference.

    • The references.insert method's documentation has been updated to properly reflect that the API uses two different endpoints for that method. This does not represent a change in API functionality, but rather a correction to the existing documentation.

      • If the request is uploading a new reference file, the correct endpoint is:

        POST https://www.googleapis.com/upload/youtube/partner/v1/references

      • If the request is creating a reference using a claimed video as the reference content, the correct endpoint is:

        POST https://www.googleapis.com/youtube/partner/v1/references

  • New and updated errors

    The table below identifies new errors that the API supports and the methods that could return each error. Note that a method may return multiple errors that have the same error type.

    Please refer to the error documentation for each method or to the errors page for more information.

    Error type Error detail Description
    badRequest (400) invalidLabelName The assets.insert, assets.update, and assetLabels.insert methods return this error if an asset label's name is invalid. Label names must be between two and 30 characters. They may not contain angled brackets, commas, colons, ampersands, or the vertical pipe character (|).
    badRequest (400) ownerHaveMaximumNumberOfLabels The assets.insert, assets.update, and assetLabels.insert methods return this error if a content owner has already defined 2500 unique asset labels, which is the maximum number currently allowed.
    badRequest (400) tooManyLabelsOnOneAsset The assets.insert and assets.update methods return this error if an asset is already associated with 30 asset labels, which is the maximum number currently allowed.
    badRequest (400) channelMonetizationSuspended The claims.insert and claims.update methods return this error if a video's channel is suspended for partner claims.
    badRequest (400) channelNotActive The claims.update method returns this error if a video's channel is not active.

  • The assets.insert and assets.update methods no longer return a badRequest error for some assets if the resource in the request body does not contain the metadataMine.contentType property.

September 23, 2014

This update contains the following changes:

  • Content Owner ID changes

    The content owner ID changes announced in the revision history on July 9, 2014, have gone into effect. As a result of this change, the API now returns a generated, unique ID to identify the content owner associated with either the authenticated user or a resource managed through the API. Previously, the API returned a human-readable name as the ID, such as "qrs_network."

    This change affects the following API functionality and will likely impact partners who have hard-coded Partner Codes in their applications.

    • The API now returns the new ID as the value of resource properties that previously returned the Partner Code, such as the contentOwner resource's id property.
    • All of the API's methods support the onBehalfOfContentOwner parameter, which identifies the content owner on whose behalf the API request is being made. Following the change, the parameter should be set to the new ID instead of the Partner Code. To prevent code breakages, the parameter will accept either value during a transition period.
    • Following the change, the contentOwners.list method's contentOwnerId parameter should specify the new ID instead of the Partner Code.

  • Updates to existing resources and methods

    • The assetSearch.list method's new metadataSearchFields parameter lets you specify asset metadata fields that you want to search as well as the values that you want to search for in those fields. The parameter value is a comma-separated list of field and value pairs; within a pair, the field and value are separated by a colon.

    • The claim resource's new appliedPolicy object specifies the policy that YouTube actually applies for the claim. The object's value is a policy resource. That resource contains policy information for the countries where the content owner that submitted the request owns the claimed asset.

      The applied policy can differ from the policy that the content owner defined in two ways:

      1. It accounts for policies set by other owners who have partial ownership of the claimed asset in some of the same territories as the content owner that submitted the API request.

      2. It accounts for YouTube administrative policies that apply in territories where the content owner owns the claimed asset.

    • The claimHistory resource's new uploaderChannelId property identifies the channel ID of the channel to which the claimed video was uploaded.

September 8, 2014

This update contains the following changes:

  • New resources and methods

    • The new assetLabel resource identifies a text label that can be assigned to an asset. Asset labels let you place assets into custom categories, making it easier to organize your asset library. You can search for assets based on their labels, which can also simplify use cases that require you to update specific groups of assets.

      • The assetLabels.list method lets you retrieve a list of a content owner's labels.
      • The assetLabels.insert method lets you create a new asset label. You can also create new labels by calling the assets.update method and updating the labels for an asset. The API server will automatically create a new assetLabel resource for any previously undefined label.

  • Updates to existing resources and methods

    • The asset resource's label[] property has been updated to note that you can call the assets.update method to update an asset's labels. However, you cannot set an asset's labels when calling the assets.insert method.

      The new Using Asset Labels guide explains how to create and retrieve asset labels as well as how to update an asset's labels or search for assets associated with particular labels.

  • New and updated errors

    The API supports several new errors for the new assetLabels.list and assetLabels.insert methods.

July 9, 2014

This update contains the following changes:

  • Content Owner ID changes

    Historically, the API has used a human-readable Partner Code, such as "qrs_network", to uniquely identify the content owner associated with either the authenticated user or a resource managed through the API. In Q3 2014, the API will switch to instead use a unique 22-character ID to identify content owners. The change affects the following API functionality and will likely impact partners who have hard-coded Partner Codes in their applications.

    • The API will return the 22-character ID as the value of resource properties that previously returned the Partner Code, such as the contentOwner resource's id property.
    • All of the API's methods support the onBehalfOfContentOwner parameter, which identifies the content owner on whose behalf the API request is being made. Following the change, the parameter should be set to the 22-character ID instead of the Partner Code. To prevent code breakages, the parameter will accept either value during a transition period.
    • Following the change, the contentOwners.list method's contentOwnerId parameter should specify the 22-character ID instead of the Partner Code.

  • Updates to existing resources and methods

    • An asset resource now supports the label property, which specifies a list of asset labels associated with the asset. You can apply a label to multiple assets to group them. You can use the labels as search filters to perform bulk updates, to download reports, or to filter YouTube Analytics.

    • The assetSearch.list method now supports the following optional parameters:

      • labels: Restricts results to only include assets that are associated with the specified labels. By default, the API returns assets that match all of the specified labels. However, you can use the includeAnyProvidedLabel parameter to instruct the API to return assets that match any of the specified labels.
      • includeAnyProvidedLabel: Used in conjunction with the labels parameter, this parameter instructs the API return assets that are associated with any of the labels specified in the labels parameter value.

    • A claimHistory resource now contains the following new properties:

    • The claimSearch.list method now supports the following optional parameters:

      • createdAfter: Restricts results to only include claims created after the specified date.
      • createdBefore: Restricts results to only include claims created before the specified date.
      • includeThirdPartyClaims: Used in conjunction with the videoId parameter, this parameter indicates whether to include third-party claims in the API results.

  • More detailed error information

    The error documentation now specifies the HTTP response code for each error type.

  • New and updated errors

    The table below identifies new errors that the API supports and the methods that could return each error. Note that a method may return multiple errors that have the same error type. For example, a required error is returned if you try to insert an asset resource that is missing a required metadata field. In fact, there may be more than one required metadata field, each of which will return an error with a slightly different message.

    Please refer to the error documentation for each method or to the errors page for more information.

    Method Errors
    assetSearch.list
    • invalidValue – The API does not support the ability to search for show or season assets. Change the value of the type parameter to a supported value.
    assets.insert
    • conflict – Too many assets with the same identifier (e.g. custom ID, ISRC, etc.) already exist.
    • conflict – Too many copies of the specified asset already exist.
    • invalidValue – The user calling the API does not have permission to create assets of the specified type.
    assets.patch
    assets.update
    • badRequest – The API does not support the asset type conversion you have attempted.
    claimSearch.list
    ownership.patch
    ownership.update
    • badRequest – You cannot update ownership of an art track asset.
    references.patch
    references.update
    • badRequest – The reference is in an invalid state for the operation you are attempting.

February 3, 2014

This update contains the following changes:

  • Updates to existing resources and methods

    • An asset resource can now have a type value of art_track_video.

    • A claimSearch resource now includes the following new properties:

      • The origin object contains information that describes the manner in which the claim was created.
      • The thirdPartyClaim property contains a Boolean value that indicates whether the claim was made by a content owner other than the one associated with the user performing the search.

    • The claimSearch.list method now supports the following optional parameters:

      • contentType: Restricts results to only include either audio-only claims, video-only claims, or audiovisual claims.
      • origin: Specifies one or more claim origins, such as descriptiveSearch or videoMatch, for which you want to find claims.
      • status: Restricts results to only include claims that have the specified status.

    • The claim resource's status property now supports the following additional values: appealed, disputed, potential, takedown, and unknown.

    • The claim resource's new blockOutsideOwnership property indicates whether the claimed video should be blocked in territories where it is not explicitly owned. By default, a claimed video would still be viewable in countries where ownership data had not been defined for the asset associated with the claim.

    • The contentOwnerAdvertisingOption resource's new allowedOptions.autoGeneratedBreaks property indicates whether the partner can opt to show midroll, in-stream ads at break times automatically determined by YouTube.

    • The contentOwners.list method can now be called with an authorization token that specifies the https://www.googleapis.com/auth/youtubepartner-content-owner-readonly scope.

    • The policy resource's new timeUpdated property specifies the time when the policy was last updated.

    • The policies.list method now supports an optional sort parameter, which can be used to specify that results should be sorted in ascending or descending order of the time they were last updated.

    • The referenceConflict resource's new expiryTime property specifies the time when the review period for the reference conflict will end, causing the conflict to expire.

    • The videoAdvertisingOption resource's new autoGeneratedBreaks property indicates whether the video should show midroll, in-stream ads at break times automatically determined by YouTube.

  • New and updated errors

    The table below identifies new errors that the API supports and the methods that could return each error. Note that a method may return multiple errors that have the same error type. For example, a required error is returned if you try to insert an asset resource that is missing a required metadata field. In fact, there may be more than one required metadata field, each of which will return an error with a slightly different message.

    Please refer to the error documentation for each method or to the errors page for more information.

    Method Errors
    assets.insert
    assets.update
    • badRequest – The API does not support write operations on art track assets.
    claimSearch.list
    • invalidValue – The pageToken parameter in the request specifies an invalid page token.
    claims.insert
    • badRequest – The claim you are trying to create is invalid because the video's channel is not active.
    • badRequest – The video you are trying to claim is exempt from a takedown policy. For inquiry, please contact copyright@youtube.com
    • badRequest – Your request cannot be processed because you cannot create a third-party claim on the specified video.
    • conflict – YouTube cannot create the requested claim because the video has countered a takedown notice.
    • conflict – YouTube cannot create the requested claim because the video has an active takedown claim.
    references.insert
    • badRequest – The claimed video that you are trying to use was deleted or rejected, or its processing failed.

  • The contentOwnerNotProvided and internalError errors, which are not specific to a particular API method, are no longer listed on every method page. Their descriptions can still be found in the General errors section of the API's error documentation.

September 12, 2013

This update contains the following changes:

  • New resources and methods

    • The new referenceConflict resource identifies a conflict between two reference files and lists the matches that existed between those files when the conflict was identified. The referenceConflicts.list method lets you retrieve a list of unresolved reference conflicts associated with the authorized content owner. The referenceConflicts.get method enables you to retrieve a reference conflict by specifying its unique reference conflict ID.

    Updates to existing resources and methods

    • The API now supports the ability to retrieve the effective match policy for an asset. This change parallels the changes released July 16, 2013, which included support for retrieving the canonical set of metadata and ownership data for an asset.

      To retrieve the effective match policy for an asset, set the fetchMatchPolicy parameter value to effective when calling either the assets.get or assets.list methods. In the API response, the matchPolicyEffective object in each returned asset resource contains the effective match policy for that asset.

    • The asset resource's new ownershipConflicts object contains information about the asset's ownership conflicts. The object's structure is similar to the structure of an ownership resource, which identifies each different type of rights that an asset owner can hold. (For most asset types, owners can just have general asset ownership, but for composition assets, owners can itemize their ownership of performance rights, synchronization rights, or mechanical rights.)

      Similarly, the ownershipConflicts object contains separate lists that identify conflicts for general ownership rights, performance rights, synchronization rights, and mechanical rights. For each conflict, the data identifies the territories where the conflict occurs, the owners who have provided conflicting ownership data, and the percentage of the asset that each conflicting owner claims to own.

    • The assets.get and assets.get methods now support the new fetchOwnershipConflicts parameter. The parameter has a boolean value that indicates whether the API request should retrieve ownership conflicts for the assets in the API response. The default value is false, which means that ownership conflicts are not returned.

    • The definition of the assetSearch.list method's q parameter has been updated to identify the metadata fields that YouTube searches.

    • The documentation of the request body for a references.insert method now indicates that you must set the value of the contentType property. This change updates the documentation to properly reflect actual API functionality but does not represent a change in API functionality.

  • New and updated errors

    • The API supports a new forbidden error, which is not specific to a certain method, that indicates that the requested operation cannot be authorized by a service account.

    • The assets.insert method now identifies metadata errors as occurring in properties in the metadataMine object rather than in the metadata object, which was deprecated as of the API update on July 16, 2013.

    • The errors page has been updated so that for each resource that supports update and patch methods, the page contains one table that lists errors returned by those two methods. Previously, the page listed the errors for each method separately, though the lists were always the same.

July 16, 2013

This update contains the following changes:

  • New resources and methods

    • The new claimHistory.get method lets you identify and retrieve information about a specific claim. The returned claimHistory resource contains a list of events related to the claim, such as the claim being created, updated, disputed, or closed.

    • The new claimSearch.list method lets you search for claims that meet any or all of the following criteria:

      • The claims are associated with a specific asset.
      • The claims are associated with a specific video.
      • The claims match a query string provided in the request.

      Each claimSnippet resource in the API response contains details about a claim, including that claim's unique claim ID, its status, its type (audio, video, or audiovisual), and the asset and video associated with the claim. The resource also specifies the number of views for the claimed video and the claimed video's title.

  • Updates to existing resources and methods

    • The documentation now lists the supported values for properties that have a set of enumerated values. Such properties include the asset resource's type property and the claim resource's status property.

    • For the assets.get and assets.list methods, the API now supports comma-separated values for the fetchMetadata and fetchOwnership request parameters, enabling you to retrieve multiple sets of metadata or ownership data.

      The list below explains the corresponding changes to the asset resource's structure as well as the impacts of those changes on API methods that get, list, insert, update, or patch asset resources.

      • The metadata object has been deprecated and replaced by the metadataMine and metadataEffective objects. The new objects allow an asset resource to include both the set of metadata provided by the content owner making the API request as well as the canonical set of metadata that YouTube has determined is the most accurate, complete set of metadata for the asset.

      • Similarly, the ownership object has been replaced with the ownershipMine and ownershipEffective objects.

      • The matchPolicy object has been replaced with the matchPolicyMine object. (The API does not currently support the ability to retrieve the effective match policy for an asset.)

      Note: To ensure backward compatibility, if only one metadata version, one set of ownership data, or one match policy is requested for an asset, the API response will include the deprecated object as well as the newly supported object. For example, if a request sets the fetchMetadata parameter to mine, the API response will contain a metadata object and a metadataMine object, both of which will contain the same data. (The ability to set fetchMetadata=mine was supported prior to the feature update enabling you to retrieve multiple metadata versions.)

      However, if the fetchMetadata parameter is set to mine,effective, the API response will contain metadataMine and metadataEffective objects, but it will not contain a metadata object. (The ability to set fetchMetadata=mine,effective was not supported prior to this feature update, so there is no need to return the metadata object for backward compatibility.) The same principle also applies to the fetchOwnership and fetchMatchPolicy parameters.

      Similarly, for backward compatibility, a request to insert, update, or patch an asset resource can include either the metadataMine object or the metadata object. The same principle applies to setting an asset resource's ownership data or match policy.

    • The claims.list method's assetId, q, and videoId parameters have been deprecated. To search for claims using any of these criteria, use the claimSearch.list method, which supports all of those parameters.

    • In an ownership resource, the values of the general[].ratio, performance[].ratio, synchronization[].ratio, and mechanical[].ratio properties all now have a content format of double instead of integer.

    • The definition of the policy resource's rules[].action property now lists valid values for that property: block, monetize, takedown, and track. However, note that you cannot use the API to apply a takedown policy to a claim.

    • The reference resource's new claimId property is present if the reference was created by associating an asset with an existing YouTube video that was uploaded to a YouTube channel linked to your CMS account. In that case, this field contains the ID of the claim that represents the resulting association between the asset and the video.

    • The reference resource's new excludedIntervals[] property specifies a list of time intervals during the reference that YouTube should ignore when trying to match the reference. Each interval specifies a start and end time measured in seconds from the start of the video.

    • The API no longer requires the status property to be set in the reference resource that is sent in the body of a references.update or references.patch request.

    • The documentation has been corrected to properly describe the API response format for the videoAdvertisingOptions.getEnabledAds method. The response, which is a youtubePartner#videoAdvertisingOptionGetEnabledAds resource, contains the following information:

      • id – The ID that YouTube uses to uniquely identify the claimed video associated with the settings.

      • adBreaks – A list of objects in which each object contains information about a point before, during, or after the video playback when ads are allowed to run. Each object may also specify other attributes of the ad break, such as the ad slots that occur during the break and the types of ads that are allowed to run during each slot.

      • adsOnEmbeds – A boolean field that indicates whether YouTube can show ads when the video is played in an embedded player.

      • countriesRestriction – A list of objects in which each object identifies a list of territories and the ad formats that are used during playbacks of the video in those territories.

  • New and updated errors

    • The table below identifies new errors that the API supports and the methods that could return each error. It also identifies errors that have changed. Note that a method may return multiple errors that have the same error type. For example, a required error is returned if you try to insert an asset resource that is missing a required metadata field. In fact, there may be more than one required metadata field, each of which will return an error with a slightly different message.

      Please refer to the error documentation for each method or to the errors page for more information.

      Method Errors
      assets.insert
      assets.update
      assets.patch
      • invalidValue and required errors previously associated with child properties of the metadata object are now associated with the same child properties in the metadataMine object.
      claimHistory.get
      • notFound – The claim for which you are trying to retrieve history cannot be found.
      • required – The request does not specify a value for the claimId parameter.
      claimSearch.list
      claims.list
      • badRequest – The request specifies invalid criteria. At most, one of the following filter parameters may be specified: q, assetId, videoId.
      claims.insert
      • badRequest – The claim you are trying to create is invalid because the requested content owner is not an owner of the asset associated with the claim.
      • badRequest – The content owner that you are acting on behalf of does not have permission to create policies with the specified action.
      • invalidValue – The content owner that you are acting on behalf of does not have permission to claim user-uploaded videos via the API.
      contentOwners.list
      • badRequest – The request specifies invalid criteria. Exactly one of the following filter parameters must be specified: fetchMine, id. (Previously, the error listed a different set of filter parameters – has_conflicts_with, restrict_to_user, name_prefix, and id.)
      ownership.update
      ownership.patch
      • badRequest – A request that updates the ownership data of a composition asset must specify granular ownership data &ndahs; mechanical, performance, synchronization, and/or lyric rights – rather than general ownership rights. The lyric rights type is newly supported.
      policies.insert
      policies.update
      policies.patch
      • invalidValue – The request contains an invalid policy rule because the API does not support the creation or modification of policies that specify a takedown action. This error, which reports a reason of invalidPolicyTakedownAction, replaces the deprecated invalidPolicyConditionalTakedown error.
      references.insert
      • badRequest – The request must either send a media file or specify a value for the claimId request parameter. However, a request may not send a media file and specify a value for the claimId request parameter.
      • badRequest – A reference for the same content has already been created from a different claim on the same YouTube video.
      • badRequest – The API does not support the ability to set a value for the fpDirect property when creating a reference.
      • internalError – There is a problem with the uploaded media file.
      • invalidValue – The value of the contentType, assetId, or claimId request parameter is invalid. The error identifies the invalid value.
      • notFound – The asset or claim that you specified cannot be found. Please check the assetId and claimId parameter values in your request.
      • required – The request must specify a value for the contentType parameter.
      references.insert
      references.update
      references.patch
      • invalidValue – The excludedIntervals specified for the reference are not valid. Note that you cannot specify exclusion intervals when deactivating a reference.

May 10, 2013

This update contains the following changes:

April 8, 2013

This update contains the following changes:

  • The API has been renamed to the YouTube Content ID API.

  • Several properties have changed in the assetMatchPolicy resource:

    • The kind property value has changed from youtubePartner#policy to youtubePartner#assetMatchPolicy.
    • The new policyId property contains a value that uniquely identifies a saved policy resource.
    • The rules[].subaction property value is now a list of strings rather than a string.
    • The rules[].conditions.contentMatchType property value is now a list of strings rather than a string.
    • The id, name, and description properties have been removed.

  • The documentation for the assetMatchPolicy.update method has been updated to reflect the fact that you can set values for either the policyId property or the rules[] object when calling the method.

  • The claims resource now supports several new properties:

    Property name Value Description
    timeCreated datetime The date and time that the claim was created.
    matchInfo object The matchInfo object contains information about the matching content that generated the claim. This information is only included in a claim resource if the claim was automatically generated because an uploaded video matched an existing reference file.
    matchInfo.referenceId string The unique ID that YouTube uses to identify the reference reference that generated the match.
    matchInfo.longestMatch object The longestMatch object contains information about the longest match between the reference and the uploaded video.
    matchInfo.longestMatch.durationSecs unsigned long The duration of the match, in seconds.
    matchInfo.longestMatch.userVideoOffset unsigned long The time offset when the match begins, measured in seconds from the beginning of the uploaded video.
    matchInfo.longestMatch.referenceOffset unsigned long The time offset when the match begins, measured in seconds from the beginning of the reference.
    matchInfo.totalMatch object The totalMatch object contains information about the total amount of the uploaded video that matched the reference and about the total amount of the reference that matched the uploaded video. These values may differ if the matching content runs in a loop in either the uploaded video or the reference. For example, if an uploaded video includes a 10-second clip from a reference, but the clip is repeated six times, then the total matching content in the uploaded video is 60 seconds, but the total matching content in the reference is only 10 seconds.
    matchInfo.totalMatch.userVideoDurationSecs unsigned long The total length, in seconds, of the uploaded video's content that matches the reference.
    matchInfo.totalMatch.referenceDurationSecs unsigned long The total length, in seconds, of the reference content that matches the uploaded video.
    origin object The origin object contains information that describes the source of the claim.
    origin.source string The source of the claim.

  • The policy property in the claims resource has been updated to note that the value cannot be updated for an AudioSwap claim.

  • The metadataHistory resource's timeProvidedMs property has been renamed to timeProvided.

  • The ownershipHistory resource's timeProvidedMs property has been renamed to timeProvided.

  • The definition of the ownershipHistory.list method has been updated to note that the method only retrieves the most recent ownership data for each content owner. However, if the content owner has submitted ownership data through multiple data sources (API, content feeds, etc.), the list will contain the most recent data for each content owner and data source.

  • Several properties have changed in the policy resource:

    • The rule property has been renamed to rules.
    • The rules[].subaction property value is now a list of strings rather than a string.
    • The rules[].conditions.contentMatchType property value is now a list of strings rather than a string.

  • The documentation for the policies.insert and policies.update methods has been updated to reflect the fact that you can set values for the rules[] object when calling those methods.

  • Several API methods support new error types. The table below identifies the method and briefly identifies the types of newly supported errors. In many cases, there may be multiple errors for a given type. For example, a required error is returned if you try to insert an asset resource that is missing a required metadata field. In fact, there may be more than one required metadata field, each of which will return an error with a slightly different message.

    Please refer to the error documentation for each method or to the errors page for more information.

    Method Errors
    assets.insert
    • invalidValue – An asset metadata field contains an invalid value.
    • required – A required asset metadata field is missing.
    assets.update
    assets.patch
    • forbidden – The asset being updated is not owned by the partner attempting to complete the update.
    • invalidValue – An asset metadata field contains an invalid value.
    • notFound – The asset is being associated with a season asset or show asset that cannot be found.
    • required – A required asset metadata field is missing.
    claims.insert
    • badRequest – The request attempts to claim a video, but the claim is not allowed.
    ownership.update
    ownership.patch
    • badRequest – The request defines total ownership greater than 100 percent within a territory.
    policies.insert
    policies.patch
    policies.update
    • conflictingPolicyRules – The policy contains conflicting policy rules.

  • The new errors page lists errors that the API can return. The page includes general errors, which might occur for multiple different API methods, as well as method-specific errors.

January 18, 2013

This update contains the following changes:

  • The newly documented videoAdvertisingOptions.getEnabledAds method lets you retrieve details about the types of ads that are allowed for a specified partner- or user-uploaded video.

  • The definition of the assetSearch.list method's ownershipRestriction parameter has been updated to note that the default parameter value is mine, which indicates that the API should only retrieve assets owned by the current user.

  • The assets.list method's documentation reflects the following changes:

    • The id parameter is now required.

    • The newly supported fetchMatchPolicy parameter lets you indicate whether the API request should also retrieve the match policy that you have set for the asset.

    • The newly supported fetchOwnership parameter lets you indicate whether the API request should also retrieve ownership data for the asset.

    • The list of assets that the API returns no longer contains pagination data. As a result, the nextPageToken property and the pageInfo object have both been removed from the API response. The pageInfo object contained the totalResults, resultsPerPage, and startIndex properties.

  • The claims resource documentation has been updated to note that you must specify a policy when creating a claim. (YouTube does not currently apply your default usage policy if an inserted claim does not specify a policy, though the documentation previously indicated that that did happen.)

  • The policy resource's hasUnpublishedDraft property has been deprecated.

  • The policies.list method's newly supported id parameter lets you identify the saved policies that the API request should retrieve. Only policies belonging to the currently authenticated content owner can be retrieved.

  • The definition of the releaseClaims parameter for both the references.patch and references.update method has been updated to note that the parameter only works when the claim's status is being updated to inactive. In that case, you can also set the releaseClaims parameter's value to true to release all match claims produced by the reference.

  • The references.patch and references.update methods have both been updated to note that you must specify the reference's status when performing either of these operations.

  • Several API methods support new error types. The table below identifies the method and the newly supported errors:

    Method Error type Error detail Description
    guideCategories.list notFound Unavailable The asset for which you are trying to retrieve the match policy cannot be found.
    claims.get notFound Unavailable The claim that you are trying to retrieve cannot be found.
    ownership.patch invalidValue Unavailable The ownership data that you provided contains an invalid value.
    ownership.update invalidValue Unavailable The ownership data that you provided contains an invalid value.