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.
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
}POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
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.
| Field | Type / example | Requiredness | Purpose |
|---|---|---|---|
| content | string | Shown in example | Video description |
| platforms[].platform | string: "youtube" | Shown in example | Target platform |
| platforms[].accountId | string: "yt_789" | Shown in example | Connected YouTube account |
| platforms[].platformSpecificData.title | string | Shown in example | Video title |
| platforms[].platformSpecificData.visibility | string: "public" | Shown in example | Public, unlisted, or private visibility |
| platforms[].platformSpecificData.tags | array of strings | Shown in example | Video tags |
| platforms[].platformSpecificData.categoryId | string: "28" | Shown in example | YouTube category |
| mediaItems[].type | string: "video" | Shown in example | Media type |
| mediaItems[].url | string URL | Shown in example | Public video URL |
| mediaItems[].thumbnail | string URL | Shown in example | Custom thumbnail URL |
| publishNow | boolean: true | Shown in example | Immediate publishing |
| scheduledFor | string datetime | Alternative to publishNow in scheduled example | Queued publishing time, with optional IANA timezone |
Field map derived from the preserved Video Post request example; types shown as observed JSON types.
| Check | Pass condition | Failure action |
|---|---|---|
| Response status | 202 with success true and status published | Do not treat the video as published |
| Per-platform result | platforms[].success true for youtube | Investigate the platform failure before retrying |
| Returned URL | platformPostUrl present | Treat publishing as unverified if absent |
| Webhook outcome | Success webhook received | Use failure webhook to update application state |
| Scheduled cancellation | Cancelled while status is still scheduled | No YouTube upload exists; safe to stop the queued post |
| In-flight cancellation | Publishing has already started | Cancellation cannot undo the in-flight upload |
| Format check | MP4, MOV, MPEG, AVI, WMV, FLV, WebM, 3GPP, ProRes, or HEVC | Replace the file; MP4 is recommended |
| Size check | At or below 256 GB | Reduce or replace the file |
| Duration check | Standard up to 15 minutes by default, verified up to 12 hours, Shorts up to 3 minutes | Trim 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.
{
"success": true,
"status": "published",
"postId": "post_ghi789",
"platforms": [
{
"platform": "youtube",
"success": true,
"platformPostUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
]
}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
}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"
}