YouTube

Publish a single video to a YouTube channel with optional metadata.

API overview

YouTube publishing in Postova sends one resumable upload per post and forwards a metadata payload for snippet, status, and recording details.

Use cases

Upload a single long-form video to a channel.
Preconfigure visibility, tags, language, and kid-safety metadata.
Schedule a publish timestamp when the upload should go live later.

When to use

When exactly one video should be uploaded to a channel.
When the post needs title, privacy, tags, language, or child-safety metadata.

When not to use

When you need more than one video in a single post.
When the asset is not a video file.

Examples

Scheduled upload

Publish a single video with full metadata and a future publishAt.

{
  "platforms": [
    {
      "platform": "youtube",
      "accountId": "yt_channel_123",
      "content": "Launch video for the new feature.",
      "mediaItems": [
        {
          "type": "video",
          "url": "https://cdn.postova.dev/launch.mp4"
        }
      ],
      "settings": {
        "youtube": {
          "title": "Launch video",
          "privacyStatus": "private",
          "tags": ["postova", "launch"],
          "categoryId": "22",
          "defaultLanguage": "fr",
          "embeddable": false,
          "publicStatsViewable": false,
          "publishAt": "2026-06-14T12:00:00Z",
          "selfDeclaredMadeForKids": false
        }
      }
    }
  ]
}

How to post

Connect a YouTube channel with upload permissions.
Attach exactly one video item to the post.
Set metadata fields such as title, privacy, tags, and language if needed.

Authentication

Default scopes

https://www.googleapis.com/auth/youtube.upload, https://www.googleapis.com/auth/youtube.readonly

Supported media

video
Supports exactly one video per upload.

Settings

Key	Type	Description	Default	Allowed values
`title`	string	Overrides the video title. Defaults to the post text or a fallback title. Truncated to 100 characters by the worker.	-	-
`privacyStatus`	enum	YouTube visibility for the uploaded video.	private	private, public, unlisted
`tags`	string-array	Video tags as an array or comma-separated string.	-	-
`categoryId`	string	YouTube video category identifier.	-	-
`defaultLanguage`	string	Language code used for the video metadata.	-	-
`embeddable`	boolean	Whether the video can be embedded elsewhere.	-	-
`license`	string	License value forwarded to YouTube as-is.	-	-
`publicStatsViewable`	boolean	Whether public statistics are visible.	-	-
`publishAt`	date-time	Scheduled publish timestamp forwarded to YouTube as-is.	-	-
`selfDeclaredMadeForKids`	boolean	YouTube made-for-kids flag. This maps to YouTube’s self-declared made-for-kids field.	-	-
`containsSyntheticMedia`	boolean	Declares whether the upload contains synthetic media.	-	-
`recordingDate`	date-time	Optional recording date forwarded to YouTube recording details.	-	-

Common errors

Invalid privacy status: The visibility value is unsupported by the worker or YouTube API. Fix: Use private, public, or unlisted. Unsupported values fall back to private.
Multiple videos not supported: The upload pipeline only accepts a single video file. Fix: Send exactly one video media item.

Constraints

YouTube accepts one video per upload.
Unsupported privacy values fall back to private.
The worker forwards known metadata fields and keeps unknown settings keys.

Notes

The upload worker builds a resumable upload session and sends metadata separately.

​YouTube

​API overview

​Use cases

​When to use

​When not to use

​Examples

​Scheduled upload

​How to post

​Authentication

​Default scopes

​Supported media

​Settings

​Common errors

​Constraints

​Notes