YouTube Videos & Shorts API Documentation

Kavenio publishes YouTube videos through connected YouTube accounts. Use youtube as the platform value in post targets and put YouTube-specific settings in the target’s platformSpecificData. YouTube is video-only in Kavenio. Each YouTube target uploads exactly one long-form video or Short, then optionally applies a thumbnail, playlist insertion, and first comment. YouTube Shorts use the normal resumable video upload flow. Send a qualifying vertical or square video through a YouTube target. YouTube supports eligible Shorts up to three minutes and determines classification from the uploaded video; there is no separate YouTube Shorts upload endpoint. In Kavenio’s web composer, Publish as YouTube Short appends #Shorts to the published description. That preference does not force YouTube to categorize the upload as a Short—the video must still meet YouTube’s current eligibility rules.

Quick Reference

Capability	Support
Platform key	`youtube`
Media	Exactly one `video` media item
Upload flow	Durable YouTube resumable upload with processing reconciliation
Shorts	Qualifying videos use the normal resumable upload flow
Visibility	`public`, `private`, or `unlisted`
Custom thumbnail	`platformSpecificData.thumbnailUrl` or media item `thumbnail`
Playlist insertion	`platformSpecificData.playlistId`
First comment	`platformSpecificData.firstComment`
Post analytics	`GET /v1/analytics` for views, likes, comments
Published edit	Supported for video metadata
Unpublish	Supported by changing visibility to `private`

Create A Video Post

{
  "profileId": "customer_user_123",
  "title": "Fallback video title",
  "content": "Video description shown on YouTube.",
  "mediaItems": [
    {
      "type": "video",
      "url": "https://cdn.example.com/product-launch.mp4",
      "mimeType": "video/mp4",
      "thumbnail": "https://cdn.example.com/product-launch-thumb.jpg"
    }
  ],
  "platforms": [
    {
      "platform": "youtube",
      "accountId": "acc_123",
      "platformSpecificData": {
        "title": "Product Launch Walkthrough",
        "visibility": "unlisted",
        "madeForKids": false,
        "containsSyntheticMedia": false,
        "categoryId": "28",
        "tags": ["launch", "product"],
        "playlistId": "PLxxxxxxxxxxxxx",
        "notifySubscribers": false,
        "firstComment": "Questions? Drop them here."
      }
    }
  ],
  "publishNow": true
}

kavenio posts create \
  --profile-id customer_user_123 \
  --title "Fallback video title" \
  --content "Video description shown on YouTube." \
  --publish-now \
  --media-url https://cdn.example.com/product-launch.mp4 \
  --platform youtube:acc_123 \
  --visibility unlisted \
  --made-for-kids false \
  --contains-synthetic-media false \
  --category-id 28 \
  --youtube-tag launch \
  --youtube-tag "product demo" \
  --playlist-id PLxxxxxxxxxxxxx \
  --thumbnail-url https://cdn.example.com/product-launch-thumb.jpg \
  --notify-subscribers false \
  --first-comment "Questions? Drop them here."

The YouTube response stores the uploaded video ID as the target platformPostId and returns a native watch URL.

Required Fields

Kavenio validates YouTube targets before provider upload.

Requirement	Details
Video media	Exactly one `mediaItems[]` entry with `type: "video"`
Title	Use `platformSpecificData.title`, or provide a top-level post `title`
`madeForKids`	Must be explicitly set to `true` or `false`
`containsSyntheticMedia`	Must be explicitly set to `true` or `false`

If both platformSpecificData.thumbnailUrl and the video media item’s thumbnail are present, Kavenio uses thumbnailUrl.

Platform-Specific Fields

Field	Type	Behavior
`title`	string	YouTube title, up to 100 characters. Overrides the top-level post title.
`visibility`	`"public"` \| `"private"` \| `"unlisted"`	YouTube privacy status. Defaults to YouTube’s private upload behavior when omitted.
`publishAsShort`	boolean	Stores the composer preference. In the web composer, enabling it appends `#Shorts` to the description; YouTube still determines classification.
`madeForKids`	boolean	COPPA audience declaration. Required by Kavenio validation.
`containsSyntheticMedia`	boolean	YouTube synthetic-media disclosure. Required by Kavenio validation.
`categoryId`	string	YouTube category ID, such as `"22"` or `"28"`.
`tags`	string[]	Up to 30 tags and 500 serialized characters, including separators and quotes.
`thumbnailUrl`	URL string	Custom thumbnail URL. Overrides the media item’s `thumbnail`.
`playlistId`	string	Existing YouTube playlist ID to add the uploaded video to.
`notifySubscribers`	boolean	Passed to YouTube upload as the subscriber notification preference.
`firstComment`	string	Adds a top-level comment after upload for public or unlisted videos. Maximum 10,000 characters.

Media URLs

YouTube pulls video and thumbnail bytes from your supplied URLs during publish. Video requirements:

The URL must be public and reachable when Kavenio publishes.
Private, loopback, and localhost URLs are rejected.
The response must return a non-empty body.
The response content type must be video/* or application/octet-stream.

Thumbnail requirements:

Use JPEG or PNG content.
The response must return a non-empty body.
The file must be 2 MB or smaller.

Kavenio follows safe redirects while fetching media. Scheduled posts should use URLs that remain valid until the scheduled job runs.

Thumbnails, Playlists, And First Comments

Kavenio performs post-upload follow-up actions in this order:

Upload the video.
Upload a custom thumbnail, when one is supplied.
Add the video to playlistId, when one is supplied.
Add firstComment, when one is supplied.

If YouTube initially holds or hides the API-created first comment, Kavenio clears that comment for public display through YouTube’s moderation API. Private videos cannot include firstComment because YouTube does not make comments available on private videos. If a follow-up action fails after the video upload succeeds, Kavenio includes partial raw provider data for the video and any completed follow-up actions in the target failure details. Retrying reuses that video ID and resumes unfinished follow-up actions instead of uploading a duplicate. Kavenio does not mark the target published immediately after YouTube accepts the upload. The worker polls YouTube processing status and publishes the final Kavenio lifecycle event only after processing succeeds. Provider failure and rejection reasons are recorded on a failed target. First comments require a connected YouTube credential with the youtube.force-ssl scope. If that scope is missing, Kavenio rejects the target before upload.

Shorts

publishAsShort adds #Shorts to the description. It does not force YouTube to classify a video as a Short. YouTube currently classifies eligible square or vertical videos up to three minutes according to its own rules.

Provider Project Readiness

Uploads from unverified API projects created after July 28, 2020 are restricted to private viewing until the project passes YouTube’s compliance audit. videos.insert is currently limited to 100 calls per day in the Video Uploads quota bucket, so live test plans should budget upload attempts and avoid using retries as duplicate uploads.

Scheduling

Use Kavenio’s normal scheduling fields:

{
  "title": "Scheduled YouTube upload",
  "content": "The description for the scheduled video.",
  "scheduledFor": "2027-06-16T10:00:00.000Z",
  "mediaItems": [
    {
      "type": "video",
      "url": "https://cdn.example.com/scheduled-video.mp4",
      "mimeType": "video/mp4"
    }
  ],
  "platforms": [
    {
      "platform": "youtube",
      "accountId": "acc_123",
      "platformSpecificData": {
        "visibility": "public",
        "madeForKids": false,
        "containsSyntheticMedia": false
      }
    }
  ]
}

Kavenio uploads to YouTube when the scheduled job publishes the post. Keep media URLs accessible until then.

Edit Published Videos

YouTube supports Kavenio’s published edit lifecycle for metadata updates.

curl -X POST "$KAVENIO_API_BASE_URL/v1/posts/post_123/edit" \
  -H "Authorization: Bearer $KAVENIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [
      {
        "targetId": "target_123",
        "platform": "youtube",
        "title": "Updated title",
        "content": "Updated description",
        "visibility": "private",
        "tags": ["updated", "launch"],
        "category": "28",
        "madeForKids": false,
        "containsSyntheticMedia": false
      }
    ]
  }'

Published edit can update:

title
description through content
tags
category
made-for-kids setting
synthetic-media setting
visibility

Published edit does not replace the video file, edit thumbnails, move playlist membership, or delete the YouTube video.

Unpublish Published Videos

YouTube unpublish changes the uploaded video’s visibility to private.

curl -X POST "$KAVENIO_API_BASE_URL/v1/posts/post_123/unpublish" \
  -H "Authorization: Bearer $KAVENIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [
      {
        "targetId": "target_123",
        "platform": "youtube"
      }
    ]
  }'

Lifecycle edit and unpublish require a connected YouTube credential with a scope that supports video updates, such as youtube.force-ssl.

Unsupported Cases

Kavenio does not support these YouTube actions through post publishing:

image-only posts
text-only posts
Community posts
live streams or Premieres
replacing an already-uploaded video file
editing thumbnails after initial upload
creating or deleting playlists
uploading captions or subtitles
managing monetization settings

Common Errors

Error	Meaning	Fix
`YouTube publishing requires exactly one video media item.`	The target has no video, multiple videos, or non-video media.	Send one `video` media item.
`YouTube publishing requires platformSpecificData.title or post title.`	No upload title was provided.	Set `platformSpecificData.title` or top-level `title`.
`YouTube first comments require public or unlisted video visibility.`	A private upload also requested `firstComment`.	Choose public/unlisted visibility or remove `firstComment`.
`YouTube publishing requires explicit madeForKids setting.`	The COPPA declaration is missing.	Set `madeForKids` to `true` or `false`.
`YouTube publishing requires explicit containsSyntheticMedia setting.`	The synthetic-media declaration is missing.	Set `containsSyntheticMedia` to `true` or `false`.
`YouTube video upload media must return a video/* content type.`	The media URL did not return video bytes.	Fix the URL or hosting content type.
`YouTube custom thumbnails cannot exceed 2MB.`	The custom thumbnail is too large.	Upload a JPEG or PNG thumbnail under 2 MB.
`Connected YouTube credential does not include the youtube.force-ssl scope required for first comments.`	The account cannot create the requested first comment.	Reconnect YouTube with comment permissions or omit `firstComment`.
`Connected YouTube credential does not include a scope that supports published video lifecycle updates.`	The account cannot edit or unpublish published videos.	Reconnect YouTube with update-capable permissions.

​Quick Reference

​Create A Video Post

​Required Fields

​Platform-Specific Fields

​Media URLs

​Thumbnails, Playlists, And First Comments

​Shorts

​Provider Project Readiness

​Scheduling

​Edit Published Videos

​Unpublish Published Videos

​Unsupported Cases

​Common Errors