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.
| Field | Type as shown | Requiredness | Notes |
|---|---|---|---|
| content | string | Shown in all examples | Becomes the video description on YouTube |
| platforms | array of objects | Shown in all examples | Each entry targets one platform and account |
| platforms[].platform | string | Required per entry | Use "youtube" for YouTube uploads |
| platforms[].accountId | string | Required per entry | The id of the connected account from the integrations list |
| platforms[].platformSpecificData.title | string | Required for YouTube | The video title |
| platforms[].platformSpecificData.visibility | string enum | Shown in all examples | One of public, private, or unlisted |
| platforms[].platformSpecificData.tags | array of strings | Optional | YouTube tags |
| platforms[].platformSpecificData.categoryId | string | Shown in all examples | YouTube category ID, e.g. "28" |
| mediaItems | array of objects | Shown in all examples | Contains the video to upload |
| mediaItems[].type | string | Shown in all examples | Use "video" for video uploads |
| mediaItems[].url | string | Shown in all examples | Publicly reachable URL of the video file |
| publishNow | boolean | Alternative to scheduling | Set true to publish immediately |
| scheduledFor | string datetime | Alternative to publishNow | Example: "2026-04-20T14:00:00" |
| timezone | string | Used with scheduledFor | Example: "America/New_York" |
Types and requiredness are as shown or stated in the source examples; no response or error schema was supplied.
| Category | ID |
|---|---|
| Film & Animation | 1 |
| Music | 10 |
| Education | 27 |
| Science & Technology | 28 |
| People & Blogs | 22 |
| Entertainment | 24 |
| Gaming | 20 |
| Howto & Style | 26 |
| News & Politics | 25 |
Partial list as supplied in the source; the full list is in the YouTube platform documentation.
| Failure | Check before retrying | Fix |
|---|---|---|
| Missing or invalid API key | Confirm the x-access-key header is present and matches the Access Keys page | Copy a fresh key from the dashboard and resend |
| YouTube channel not connected | List integrations and confirm a YouTube account exists | Complete the OAuth connect flow for that channel |
| Wrong or missing accountId | Compare accountId with the id returned by the integrations list | Use the exact id of the connected YouTube account |
| Missing title | Confirm platformSpecificData.title is present and non-empty | Add the video title; it is required for YouTube |
| Invalid visibility | Confirm visibility is public, private, or unlisted | Correct the enum value and resend |
| Invalid categoryId | Confirm categoryId is a string ID from the category table | Use a valid ID such as "28" for Science & Technology |
| Inaccessible video URL | Open the mediaItems URL directly and confirm the file downloads | Host the file at a reachable URL and resend |
| Scheduling misuse | Confirm scheduledFor is a valid datetime and timezone is a valid IANA name | Correct 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.
curl {{API_BASE_URL}}/v1/connect/youtube \
-H "x-access-key: YOUR_API_KEY"curl {{API_BASE_URL}}/v1/connect/integrations \
-H "x-access-key: YOUR_API_KEY"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
}'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"
}'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
}'