Skip to content

YouTube Posting API

The YouTube Posting API lets a product, automation, agency workflow, or AI system publish standard videos and YouTube Shorts through one request.

Video Post request
POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "youtube",
        "accountId": "yt_789",
        "platformSpecificData": {
          "title": "How to Build a Social Media Scheduler",
          "visibility": "public",
          "tags": ["tutorial", "api", "social media"],
          "categoryId": "28"
        }
      }
    ],
    "mediaItems": [
      {
        "type": "video",
        "url": "https://cdn.example.com/video.mp4",
        "thumbnail": "https://cdn.example.com/thumbnail.jpg"
      }
    ],
    "publishNow": true
}
Illustrative request
Example line 1

POST {{API_BASE_URL}}/v1/posts

Illustrative request
Example line 2

x-access-key: YOUR_API_KEY

Illustrative request
Example line 3

Content-Type: application/json

You supply the connected YouTube account, video media, and metadata; the endpoint handles YouTube's chunked upload process and account connection flow. This page gives the exact request fields, a worked Video Post example, Shorts and scheduling behavior, format and duration limits, and the checks needed to verify that publishing succeeded.

YouTube Posting API operation and reader task

Bring YouTube publishing into a product, automation, agency workflow, or AI system while leaving the platform upload mechanics and account linking to the endpoint. Link a YouTube account through OAuth, then call the same endpoint for standard videos and YouTube Shorts. The practical task is to publish through a single POST /v1/posts request, configure title, description, tags, visibility, category, and thumbnail, and confirm whether publishing succeeded.

Add social media in three steps: API key, integrate, support platforms

Integration follows three steps. First, get an API key through signup without a sales call or complicated setup. Second, integrate in minutes by connecting once to publish, schedule, analyze, manage comments, and handle messages through the same API. Third, support every major platform so users can reach other networks without building and maintaining each integration separately. The same endpoint and field structure are used across formats; only the fields required for each publishing format change.

Exact endpoint contract and field map

Use POST {{API_BASE_URL}}/v1/posts for Video Post, Short, and Cross-Post requests. The top-level content field carries the video description. Each entry in platforms identifies the target with platform set to youtube and accountId set to the connected YouTube account. YouTube-specific metadata belongs in platformSpecificData, including title, visibility, tags, and categoryId. Video media belongs in mediaItems, where each item uses type video, a public url, and an optional thumbnail. Set publishNow to true for immediate publishing, or use scheduledFor for queued publishing with an optional IANA timezone. For local files, use the media upload flow before publishing; for public files, pass the media URL directly in mediaItems. The Video Post request and its 202 response are shown in the examples titled Video Post request and Video Post 202 response. A Short uses the same endpoint and fields, as shown in YouTube Shorts request using the same endpoint. A scheduled request uses scheduledFor instead of publishNow, as shown in Scheduled publishing request with scheduledFor.

Shorts, metadata, visibility, tags, categories, and thumbnails

Standard videos and YouTube Shorts are both supported. A Short is an eligible square or vertical video up to 3 minutes long, published through the same POST /v1/posts endpoint as a standard video. Set the video title and tags through platformSpecificData and include the video description in content. Set visibility to public, unlisted, or private. Add tags and select a YouTube category with categoryId to improve discoverability. Supply a custom thumbnail through mediaItems[].thumbnail. Additional publishing controls include COPPA settings, synthetic-media disclosures, and a first comment. A cross-post request can target YouTube together with other platforms such as TikTok and Instagram Reels in one request by adding the relevant platform entries.

Scheduled publishing and cancellation behavior

For immediate publishing, set publishNow to true. For queued publishing, use scheduledFor with an optional IANA timezone. Scheduled videos are uploaded privately and changed to the requested visibility at publish time. While a post is still scheduled, swapping its media updates the queued post. Cancelling in that state means nothing was uploaded to YouTube. After publishing begins, an in-flight upload cannot be undone by cancellation, so treat the transition from scheduled to publishing as the point of no return. Check the returned status before assuming a queued video has been delivered.

Formats, size, and duration limits

Accepted video formats are MP4, MOV, MPEG, AVI, WMV, FLV, WebM, 3GPP, ProRes, and HEVC, with MP4 recommended. The documented ceiling is 256 GB per video. Standard videos run up to 15 minutes by default, verified accounts up to 12 hours, and Shorts up to 3 minutes. Validate format, size, and duration before sending the request, because an ineligible file can fail the Shorts categorization or exceed the applicable duration limit even when the request fields are well formed.

Publish verification via response and webhooks

After sending POST {{API_BASE_URL}}/v1/posts, inspect the response status, the top-level success and status fields, postId, and the per-platform success value. For a published YouTube video, read platformPostUrl to obtain the returned YouTube video URL. Use post webhooks to update your application when publishing succeeds or fails, rather than relying only on the initial response for asynchronous outcomes. If the per-platform success value is not true or platformPostUrl is absent, treat the video as not published and investigate before retrying.

Direct API versus wrapper decision criteria

Direct YouTube Data API integration means handling Google OAuth, account tokens, the chunked upload process, metadata, thumbnails, scheduling, and platform-specific error handling yourself. A single-endpoint wrapper accepts the connected YouTube account, video, and metadata, then handles the YouTube-specific publishing process behind the same endpoint used for other supported social networks. Choose the wrapper when you need consistent publishing, scheduling, analytics, comments, and messaging across platforms; choose direct integration when you need fine-grained control over the native YouTube flow and are prepared to maintain OAuth, tokens, chunked upload, and error handling. Related capabilities include YouTube scheduling for queue control, YouTube analytics for performance data, and YouTube comments for listing, replying to, and deleting comments. The endpoint can be called from a developer stack with typed SDKs and REST, from no-code tools such as Zapier, Make, and n8n, or from AI agents through a hosted MCP server, agent skills, and an OpenAI tool-calling schema. Beyond YouTube, the same connected-account model covers Twitter / X, Instagram, Facebook, TikTok, Threads, Pinterest, LinkedIn, Bluesky, and Google Business, with additional scheduling, analytics, comments, messaging, and comment-to-DM capabilities available through the same API.

POST /v1/posts field map
FieldType / exampleRequirednessPurpose
contentstringShown in exampleVideo description
platforms[].platformstring: "youtube"Shown in exampleTarget platform
platforms[].accountIdstring: "yt_789"Shown in exampleConnected YouTube account
platforms[].platformSpecificData.titlestringShown in exampleVideo title
platforms[].platformSpecificData.visibilitystring: "public"Shown in examplePublic, unlisted, or private visibility
platforms[].platformSpecificData.tagsarray of stringsShown in exampleVideo tags
platforms[].platformSpecificData.categoryIdstring: "28"Shown in exampleYouTube category
mediaItems[].typestring: "video"Shown in exampleMedia type
mediaItems[].urlstring URLShown in examplePublic video URL
mediaItems[].thumbnailstring URLShown in exampleCustom thumbnail URL
publishNowboolean: trueShown in exampleImmediate publishing
scheduledForstring datetimeAlternative to publishNow in scheduled exampleQueued publishing time, with optional IANA timezone

Field map derived from the preserved Video Post request example; types shown as observed JSON types.

Failure and verification matrix
CheckPass conditionFailure action
Response status202 with success true and status publishedDo not treat the video as published
Per-platform resultplatforms[].success true for youtubeInvestigate the platform failure before retrying
Returned URLplatformPostUrl presentTreat publishing as unverified if absent
Webhook outcomeSuccess webhook receivedUse failure webhook to update application state
Scheduled cancellationCancelled while status is still scheduledNo YouTube upload exists; safe to stop the queued post
In-flight cancellationPublishing has already startedCancellation cannot undo the in-flight upload
Format checkMP4, MOV, MPEG, AVI, WMV, FLV, WebM, 3GPP, ProRes, or HEVCReplace the file; MP4 is recommended
Size checkAt or below 256 GBReduce or replace the file
Duration checkStandard up to 15 minutes by default, verified up to 12 hours, Shorts up to 3 minutesTrim or replace the file before publishing

Behavior statements preserved from source FAQ and capability copy.

Frequently asked questions

What can I publish with the YouTube Posting API?

Standard videos and YouTube Shorts are supported. Through the publishing request you can set the title, description, tags, visibility, category, custom thumbnail, COPPA settings, synthetic-media disclosure, and an initial comment.

Why use a wrapper instead of the YouTube Data API directly?

Going direct means you own Google OAuth, account tokens, the chunked upload process, metadata, thumbnails, scheduling, and platform-specific error handling. A single-endpoint wrapper takes the connected YouTube account, video, and metadata, then runs the YouTube-specific publishing process behind the same endpoint used for other supported networks.

Can I upload YouTube Shorts through the API?

Yes. An eligible square or vertical video up to 3 minutes long can be categorized as a Short. Shorts go through the same POST /v1/posts endpoint as standard YouTube videos.

What video formats does the YouTube Posting API support?

MP4, MOV, MPEG, AVI, WMV, FLV, WebM, 3GPP, ProRes, and HEVC are supported. MP4 is recommended.

What is the maximum YouTube upload size?

The documented ceiling is 256 GB per video. Standard videos run up to 15 minutes by default, verified accounts up to 12 hours, and Shorts up to 3 minutes.

Can I schedule YouTube videos?

Send POST /v1/posts with scheduledFor and, if needed, an IANA timezone. The post stays queued until the scheduled time, when the video is uploaded with the requested visibility. If you swap the media while the status is still scheduled, the queued post is updated; if you cancel in that state, nothing was uploaded to YouTube. After publishing begins, an in-flight upload cannot be undone by cancellation.

How do I know whether my YouTube video actually published?

Look at the publishing status and YouTube video URL in the API response. Post webhooks can also notify your application when publishing succeeds or fails.

What can I build with the YouTube Posting API?

SaaS products, social media management tools, content repurposing workflows, agency platforms, and AI agents can add YouTube publishing through this endpoint without maintaining a separate YouTube upload flow.

Video Post 202 response
{
    "success": true,
    "status": "published",
    "postId": "post_ghi789",
    "platforms": [
      {
        "platform": "youtube",
        "success": true,
        "platformPostUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
      }
    ]
}
YouTube Shorts request using the same endpoint
POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "youtube",
        "accountId": "yt_789",
        "platformSpecificData": {
          "title": "A vertical video for YouTube Shorts",
          "visibility": "public",
          "tags": ["shorts", "tutorial"],
          "categoryId": "28"
        }
      }
    ],
    "mediaItems": [
      {
        "type": "video",
        "url": "https://cdn.example.com/short.mp4",
        "thumbnail": "https://cdn.example.com/short-thumbnail.jpg"
      }
    ],
    "publishNow": true
}
Scheduled publishing request with scheduledFor
POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "youtube",
        "accountId": "yt_789",
        "platformSpecificData": {
          "title": "Scheduled YouTube video",
          "visibility": "public",
          "tags": ["tutorial", "api"],
          "categoryId": "28"
        }
      }
    ],
    "mediaItems": [
      {
        "type": "video",
        "url": "https://cdn.example.com/scheduled-video.mp4",
        "thumbnail": "https://cdn.example.com/scheduled-thumbnail.jpg"
      }
    ],
    "scheduledFor": "2026-01-15T14:00:00Z"
}