Skip to content

How to upload YouTube video via API

Uploading a YouTube video via API requires four things: an API key, a linked YouTube channel, a video file reachable at a public URL, and the metadata YouTube expects. This walkthrough uses a managed posting service, so you make a single JSON request rather than building Google Cloud configuration, OAuth token management, and YouTube's resumable upload handling yourself. Your request supplies the file location and metadata; the service retrieves the file and completes the resumable transfer to YouTube on your behalf.

What you need

Before your first upload, confirm three prerequisites: an API key obtained from the Access Keys page in your dashboard, a YouTube channel already linked to your account, and a video file served from a URL the service can fetch. Every request carries the key in the x-access-key header, so guard it as you would a password. If any prerequisite is absent, the upload will fail; checking them in this order saves time when you later debug the request body.

Step 1: Get your API key

Create an account, open the dashboard, and copy the access key shown on the Access Keys page. Place that value in place of YOUR_API_KEY in the x-access-key header on each request shown here. Keep the key out of source control and replace it if it is ever exposed. When a request is rejected before any platform processing, a missing or incorrect key is the first thing to verify.

Step 2: Connect your YouTube channel

Channel linking is handled for you through Google OAuth, so there is no need to create a Google Cloud project or manage your own API credentials. Request the YouTube connect endpoint to obtain an authorization link, open that link, sign in with the Google account that owns the channel, and grant the requested access. After approval, the channel is linked. Then retrieve your linked integrations and identify the YouTube entry's id, since that identifier is supplied as accountId when you create a post. Linking is also available from the dashboard, which presents a visual summary of every connected account. The contract also describes this operation as GET /v1/connect/{platform}; retain that method and path exactly as written when implementing against the contract sheet.

Step 3: Upload a video

Create the upload with a POST to the posts endpoint. Put the description text in content, include one YouTube entry in the platforms array, and place the video location in mediaItems. On YouTube, content appears as the video description. Within the YouTube entry, platformSpecificData holds the platform-specific settings: title is the mandatory video title, visibility selects public, private, or unlisted, tags is an array of strings, and categoryId is the category identifier supplied as a string. Setting publishNow to true publishes right away. The service fetches the file from the URL you provide and manages YouTube's resumable transfer process, so your client only needs a reachable file URL and accurate metadata.

YouTube category IDs

Select categoryId from the category list below. Because identifiers are strings in the request, send "28" rather than 28. Choose the category that most closely fits the content, as it influences how YouTube classifies the video. The table covers the categories used most frequently; the complete list appears in the YouTube platform documentation.

Scheduling uploads

For a future publish time, omit publishNow and instead provide scheduledFor together with timezone. Transfer to YouTube begins straight away, while public availability waits until the scheduled moment arrives. Supply scheduledFor as an ISO-style datetime and timezone as an IANA name such as America/New_York, so the intended moment is unambiguous. Once scheduled, use the Posts dashboard to monitor status, filter by platform, and organize your content calendar. Expect the video not to be visible before its scheduled time.

Why not use the YouTube Data API directly?

Using the YouTube Data API directly is possible, but it means taking on several distinct responsibilities. You must create a Google Cloud project, enable YouTube Data API v3, configure an OAuth consent screen with the appropriate scopes, and seek verification if you need more than 100 users. You must also implement the OAuth 2.0 authorization code exchange, persist refresh tokens, and manage token rotation. YouTube's resumable upload is itself multi-step: you start the upload, receive a resumable URI, send the file in chunks, and handle failures and retries. Quota adds a further constraint: the default allowance is 10,000 units per day, each video upload consumes 1,600 units, and that arithmetic allows 6 uploads per day before a quota increase must be requested. A managed API takes over project setup, OAuth, resumable upload, and quota handling, leaving you to send a video URL plus metadata. Pick the direct approach when you need full control and can work within quota; pick the managed approach when you want uploads working without building that infrastructure.

Cross-post to multiple platforms

A video destined for YouTube often belongs elsewhere as well. Add further entries to the platforms array in the same request, giving each entry its own platform and accountId. YouTube receives the video together with its full metadata, while the other destinations receive the same media alongside the text content. A single request can therefore publish to YouTube, Twitter, and LinkedIn at once. Before cross-posting, verify that every accountId in the array is connected and that the media type suits each destination.

What's next

The complete sequence is: obtain your API key, link your YouTube channel through OAuth, upload a video with its metadata, select a categoryId and visibility, and, if needed, schedule with scheduledFor or cross-post to additional platforms in the same request. For the full field reference, consult the YouTube posting API documentation and the platform-specific documentation. Before a first upload to a new channel, run through the failure checklist below and check the connected accountId and video URL first, as those are the most frequent causes of a failed request.

Upload request input contract
FieldType as shownRequirednessNotes
contentstringShown in all examplesBecomes the video description on YouTube
platformsarray of objectsShown in all examplesEach entry targets one platform and account
platforms[].platformstringRequired per entryUse "youtube" for YouTube uploads
platforms[].accountIdstringRequired per entryThe id of the connected account from the integrations list
platforms[].platformSpecificData.titlestringRequired for YouTubeThe video title
platforms[].platformSpecificData.visibilitystring enumShown in all examplesOne of public, private, or unlisted
platforms[].platformSpecificData.tagsarray of stringsOptionalYouTube tags
platforms[].platformSpecificData.categoryIdstringShown in all examplesYouTube category ID, e.g. "28"
mediaItemsarray of objectsShown in all examplesContains the video to upload
mediaItems[].typestringShown in all examplesUse "video" for video uploads
mediaItems[].urlstringShown in all examplesPublicly reachable URL of the video file
publishNowbooleanAlternative to schedulingSet true to publish immediately
scheduledForstring datetimeAlternative to publishNowExample: "2026-04-20T14:00:00"
timezonestringUsed with scheduledForExample: "America/New_York"

Types and requiredness are as shown or stated in the source examples; no response or error schema was supplied.

YouTube category IDs
CategoryID
Film & Animation1
Music10
Education27
Science & Technology28
People & Blogs22
Entertainment24
Gaming20
Howto & Style26
News & Politics25

Partial list as supplied in the source; the full list is in the YouTube platform documentation.

Failure checklist for YouTube uploads
FailureCheck before retryingFix
Missing or invalid API keyConfirm the x-access-key header is present and matches the Access Keys pageCopy a fresh key from the dashboard and resend
YouTube channel not connectedList integrations and confirm a YouTube account existsComplete the OAuth connect flow for that channel
Wrong or missing accountIdCompare accountId with the id returned by the integrations listUse the exact id of the connected YouTube account
Missing titleConfirm platformSpecificData.title is present and non-emptyAdd the video title; it is required for YouTube
Invalid visibilityConfirm visibility is public, private, or unlistedCorrect the enum value and resend
Invalid categoryIdConfirm categoryId is a string ID from the category tableUse a valid ID such as "28" for Science & Technology
Inaccessible video URLOpen the mediaItems URL directly and confirm the file downloadsHost the file at a reachable URL and resend
Scheduling misuseConfirm scheduledFor is a valid datetime and timezone is a valid IANA nameCorrect the datetime and timezone and resend

Pre-flight checklist derived from the required fields and flow; no observed error responses or status codes were supplied.

Connect a YouTube channel
curl {{API_BASE_URL}}/v1/connect/youtube \
  -H "x-access-key: YOUR_API_KEY"
List connected integrations to retrieve accountId
curl {{API_BASE_URL}}/v1/connect/integrations \
  -H "x-access-key: YOUR_API_KEY"
Upload a video to YouTube
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "youtube",
        "accountId": "your-account-id",
        "platformSpecificData": {
          "title": "Building a Social Media API From Scratch",
          "visibility": "public",
          "tags": ["api", "development", "tutorial"],
          "categoryId": "28"
        }
      }
    ],
    "mediaItems": [
      { "type": "video", "url": "https://your-cdn.com/video.mp4" }
    ],
    "publishNow": true
  }'
Schedule a YouTube upload
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "youtube",
        "accountId": "your-account-id",
        "platformSpecificData": {
          "title": "Dev Log #12: New Features & Bug Fixes",
          "visibility": "public",
          "tags": ["devlog", "updates"],
          "categoryId": "28"
        }
      }
    ],
    "mediaItems": [
      { "type": "video", "url": "https://your-cdn.com/devlog-12.mp4" }
    ],
    "scheduledFor": "2026-04-20T14:00:00",
    "timezone": "America/New_York"
  }'
Cross-post one video request to multiple platforms
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "youtube",
        "accountId": "acc_yt_123",
        "platformSpecificData": {
          "title": "How to Build a REST API in 10 Minutes",
          "visibility": "public",
          "tags": ["tutorial", "api", "rest"],
          "categoryId": "28"
        }
      },
      { "platform": "twitter", "accountId": "acc_tw_456" },
      { "platform": "linkedin", "accountId": "acc_li_789" }
    ],
    "mediaItems": [
      { "type": "video", "url": "https://your-cdn.com/tutorial.mp4" }
    ],
    "publishNow": true
  }'