> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.shipcontent.com/llms.txt
> Use this file to discover all available pages before exploring further.

---
title: YouTube
description: Connect a customer channel, approve one saved video, and read the upload result.
section: channels
order: 25
status: verified-locally
mode: both
reviewed: 2026-11-19
sources: [db/publishing.sql, db/youtube.sql, db/migrations/20261109T2235_youtube_purge_metrics.sql, db/migrations/20261119T0410_youtube_upload_reliability.sql, src/lib/youtube/youtube-job-notes.ts, src/lib/server/youtube/YouTubeUploadChunks.ts, src/lib/server/youtube/YouTubeProviderUploads.ts, src/worker/YouTubeUploadFile.ts, src/worker/YouTubeUploadOutcome.ts, src/worker/YouTubeUploadSteps.ts, src/lib/marketing/delivery-error.ts, src/components/owner/media-workspace.tsx, src/components/owner/channel-actions.ts, src/lib/server/owner/connections-overview.ts, src/lib/youtube/youtube.ts, src/lib/server/marketing/service.ts, src/components/marketing/marketing-workspace.tsx, src/lib/server/youtube/YouTubeService.ts, src/lib/server/youtube/YouTubeProvider.ts, src/lib/server/youtube/youtube-callback.ts, src/lib/server/youtube/YouTubeVault.ts, src/lib/server/youtube/YouTubePrivateDatabase.ts, src/lib/server/youtube/youtube-database.ts, src/lib/server/youtube/youtube-agent-tools.ts, src/worker/YouTubePublicationWorker.ts, src/app/integrations/youtube/callback/route.ts, src/lib/social/connect-path.ts, src/lib/server/social/connect-start.ts, src/components/owner/channel-tiles.tsx, src/components/owner/youtube-controls.tsx, src/lib/server/social/connection-failure.ts, src/components/owner/connect-notice.tsx, src/components/owner/post-review.tsx, src/components/use-draft-autosave.ts, src/lib/review/draft-recovery.ts, src/lib/marketing/post-catalogue.ts, src/lib/marketing/post-scheduling.ts, src/lib/server/marketing/PostScheduling.ts, src/components/owner/post-schedule-controls.tsx, src/lib/server/youtube/YouTubeScheduledPublication.ts, .env.example, src/worker/YouTubePublicationWorkerRun.ts, src/lib/server/marketing/post-set-publish-checks.ts, src/lib/mcp/agent-youtube-tools.ts, db/migrations/20261119T0400_agent_connected_account.sql, src/lib/server/marketing/post-metrics-agent-tools.ts, src/lib/mcp/agent-post-metrics-tools.ts, src/lib/server/marketing/post-metric-mapping.ts]
tools: [start_youtube_connection, get_youtube_status, prepare_youtube_publication, publish_youtube_video, edit_post, prepare_post_schedule, get_post_schedule, publish_post, get_post_metrics, refresh_post_metrics]
next: [/docs/workflows/post-draft, /docs/start/owner-handoff, /docs/contracts/errors]
---

Publishing uses no credits and has no ShipContent publication quota. With plan enforcement on, new owner and automatic-agent approvals and an upload that has not started require publishing access. Unsent work is cancelled if that access ends. An upload that has started can still save its receipt and read its result. Exact saved approval replays remain available. Updated October 16, 2026.

Call `start_youtube_connection` and give `connectionUrl` to the owner. The link is `/connect/youtube`. The owner signs in if needed, then goes straight to Google to authorize the channel. ShipContent shows no intermediate page or policy checkbox. The first channel Google returns is saved at once. After a disconnect deletes the stored channel data, every reconnect needs the owner to confirm the destination on the return page. This is separate from ShipContent login. A password owner can connect a different Google account. Read `get_youtube_status` after the owner returns. Saved connection status does not prove current provider access.

If connection fails, the return page shows the cause and the next action, when the server knows the cause. An account with no channel must create one in YouTube or use another account. A server configuration or storage failure needs support. Unknown failures show the general retry notice. No provider diagnostic, authorization code or token appears in the return URL.

## Approve an upload

1. Create a post draft and attach one saved MP4 video.
2. Call `prepare_youtube_publication` with the `postId`. Give `reviewUrl` to the owner.
3. At the post editor, choose one video and edit the YouTube title, description, visibility, audience and synthetic-content disclosure. The editor saves the selected video and valid details in the background after 5 seconds without another edit. Each edit is kept in browser local storage immediately and restored after navigation or reload. Invalid input or a failed save stays in the editor for correction or retry. The server reads the video and saves its checksum on the post. The general hook, caption and call-to-action fields are not shown for YouTube.
4. Select **Approve and upload** to approve the saved video and settings. No separate confirmation checkbox is required. Saving alone does not upload. Approval queues one upload with a thirty-minute upload window. Editing the post after approval is blocked.
5. Read `get_youtube_status`. A queued job is not delivery. The worker verifies the returned video ID, channel, processing state and visibility. Private, unlisted and public results are distinct. Post cards also show cancelled or unknown work. A job that failed, waits or is unknown has an `error` text. See [upload results](#upload-results).

Updated 2026-10-28. **Approve and upload** sends the settings that the owner confirmed. If the saved settings changed after that, for example after an agent edit of the visibility, the approval is refused with [`CONTENT_CHANGED`](/docs/contracts/errors#recovery-by-kind). No upload is queued. The editor reads the post again: the owner checks the settings, then approves again.

The editor reads saved upload progress automatically while it is visible. The final status shows the visibility YouTube returned. There are no routine refresh or check-status buttons. If a status read fails, select **Retry**. The browser retains each unconfirmed owner action and its exact input in recovery storage. After a lost response, the editor checks the saved result. **Retry save** or **Retry upload** repeats the retained request and input. Never create a replacement upload to resolve an unknown result.

## Automatic publishing

The owner can give this agent Publish across all owned workspaces in Agents, with typed confirmation `allow agent`. Read `list_workspaces.access.canPublish`. The post must also have `publishMode: "automatic"`. Set it, and `channel: "youtube"`, with `edit_post` from the user's instruction. Then call `publish_youtube_video` with the title, description and privacy. It saves them on the post, approves them with the agent's permission and queues one upload for the same worker. Without the mode or the permission, it saves nothing and returns `mode: "owner_review"` with `reason` and `review.url`. Turning off Publish keeps queued and scheduled uploads. Disconnecting the agent cancels its unsent work in all workspaces; disconnecting the channel stops new provider work. ShipContent sets no daily limit; the YouTube upload quota of the API project still applies. When it is used up, the job fails with `YOUTUBE_QUOTA_EXCEEDED` and is not retried.

## Recovery and disconnect

If saved YouTube status cannot be read, Connections shows **Error** with **Retry**. This does not mean the server keys are missing. **Not available** indicates missing YouTube configuration.

The worker saves a resumable session before it sends a byte. It queries that session after an interrupted upload. A job has one session. A start that has no saved session sent no byte, so the job is `failed`. See [upload results](#upload-results).

Withdraw or disconnect stops new authorized upload work. An in-flight request can still finish. Disconnect deletes saved Google credentials, channel data, resumable session URLs and upload receipts from ShipContent. It preserves your saved media and the record that prevents a second upload of the same post. It does not delete YouTube videos. Reconnect and confirm the destination to use the channel again. To revoke Google consent, open [Google account permissions](https://security.google.com/settings/security/permissions). To delete a video, use YouTube Studio. You can also request data deletion at [support@shipcontent.com](mailto:support@shipcontent.com).

Updated 2026-11-06. A disconnect, and a token that Google refused, also delete the saved view, like and comment counts that the dashboard keeps for your YouTube videos. A scheduled post record can keep the channel ID.

## Upload results

Updated 2026-11-19. Before this date, a job that YouTube did not confirm stayed in `uploading` until the upload window closed. It then became `unknown` with no saved reason.

One job has one result. Read it with `get_youtube_status`.

| Status | What it means |
| --- | --- |
| `queued` | The job waits for the worker. No request went to YouTube. |
| `uploading` | The worker sends the video to the saved session. |
| `processing` | YouTube has the whole video. The worker reads its processing state. |
| `published`, `private`, `unlisted` | YouTube processed the video. The status is the visibility that YouTube returned. |
| `failed` | No video was published. It is certain that YouTube holds no video of this upload. |
| `unknown` | A video can exist. YouTube did not confirm it. |
| `cancelled` | The upload did not start. |

One rule decides between `failed` and `unknown`. A job is `failed` only when it is certain that YouTube created no video. A job is `unknown` only when a video can exist. These cases create no video: a refused session start, a refusal from YouTube, and a session that holds fewer bytes than the file. YouTube returns the video in the answer to the request that completes the file. The [resumable upload guide](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol) states that "the server responds with a `201` HTTP response code" when "the entire file has been uploaded". A `failed` upload needs a new post. The job of the first post stays as the record.

**Check before sending.** The worker saves the approved video to a temporary file one time. It compares the size and the SHA-256 with the approved values before it sends a byte to YouTube. A video that differs fails with `MEDIA_CONTENT_MISMATCH`. The worker deletes the file when the try ends, also after an error. It does not hold the whole file in memory.

**Send in chunks.** The worker sends the file to the saved session in chunks of 8 MiB. The guide states: "The chunk size must be a multiple of 256 KB." The last chunk can be smaller. Each chunk request has its own timeout of 60 seconds. Before each chunk, the worker renews its lease and checks that the upload window is open. It sends no byte after the window closes. Before the chunk that carries the last byte, the worker saves that fact. After a lost answer to that chunk, a video can exist.

**Read the session after a failure.** After a failed or timed-out chunk, the worker asks the session which bytes it holds. The request has `Content-Range: bytes */size`. The answer `308` has a `Range` header with the confirmed bytes. The worker continues from them. An answer with no `Range` header means no byte arrived. The guide states that a finished upload gives "the same response that it sent when the upload originally completed". A lost final answer does not cause a second upload.

| Answer from YouTube | Result |
| --- | --- |
| `200` or `201` with a video | The upload is complete. The worker reads the video by its ID. |
| `308` | The worker continues from the confirmed bytes. |
| `5xx`, `408`, `429`, `403` with `rateLimitExceeded` or `userRateLimitExceeded`, `403` with no reason, no answer, timeout | The failure is transient. The worker keeps the job and tries again. The wait doubles from 15 seconds to 2 minutes. This continues until the upload window closes. |
| `401` after one token refresh | Google refused the saved token. ShipContent removes the connection. |
| `403` with `quotaExceeded`, or `uploadLimitExceeded` | The job is `failed`. Publish again tomorrow. Exception: the request that reads the session got this answer after the last byte went out. Then the job stays and the worker reads the session again. |
| `404` or `410` on the session | The session is gone. The job is `failed` when the last byte was never sent. Otherwise it is `unknown`. |
| Any other `4xx`, for example `400`, `403` with another reason, or `413` | YouTube refused the upload. The job is `failed`. Exception: the request that reads the session got this answer after the last byte went out. Then a video can exist and the job is `unknown`. |

**Before the upload starts.** A transient error before the session start keeps the job. The worker tries again until the upload window closes. Then the job is `cancelled` with the text "The upload window closed before the upload started". A definite error ends the job as `failed`. The job never becomes `unknown` before it has a session.

**The session start.** The worker never starts a second session for one job. A start that YouTube refused, or that has no saved session, sent no byte. The job is `failed` with the text "YouTube did not start the upload".

**After the upload window closes.** The worker still reads a job that has a saved session. It sends no byte. A finished upload ends the job as published, private or unlisted. A session with fewer bytes than the file ends the job as `failed`. A session that holds every byte and gives no video keeps the job. When YouTube gives no answer, the job is `unknown` while it waits. The worker then reads it again, with waits that grow from 1 minute to 30 minutes. This stops 24 hours after the upload window closed. An `unknown` job that got no result in this time stays `unknown`. The worker does not read these jobs again: a job that it ended as `unknown` (a session that is gone after the last byte, a refused read of the session, or a changed channel), a job that the owner cancelled, a job with no saved session and no video ID, and a job with no connected channel or with a lapsed account. The guide does not state how long a session lasts.

**What `error` shows.** The text is a fixed note. For a call that YouTube answered, the note is followed by ` YouTube said: ` and the call, the HTTP status, the reason and the message of YouTube. At most 400 characters are kept. The text has no token and no session address. Example: `YouTube refused this upload. No video was published. Check the video and the channel in YouTube Studio. Create a new post to try again. YouTube said: chunk upload: HTTP 403 (forbidden): The caller does not have permission.` While a job waits, `error` shows the last failed call. A failure that is not an answer of YouTube, for example a storage failure, shows `The upload did not finish yet. ShipContent tries again until the upload window closes.` with no `YouTube said:` part. The owner sees the note in the language of the screen, with the next action. The owner does not see the part after `YouTube said:`. For the saved codes, see [YouTube errors](/docs/contracts/errors#youtube-errors).

## Insights

Updated 2026-11-19: `get_post_metrics` returns the views, likes and comments of each uploaded video, and `refresh_post_metrics` reads them from YouTube with the saved channel connection. The connection already holds the `youtube.readonly` permission, so the owner has nothing more to allow. `shares` is `not-returned`. A count that YouTube does not return is `not-returned`. See [Read post performance](/docs/workflows/metrics).

## Limits

One connected channel per workspace, one MP4 per post, at most 50 MiB. The title allows 100 Unicode characters and keeps the owner's text; the description allows 5000 UTF-8 bytes. Neither allows angle brackets. The authorization must return exactly one usable channel. An account with no channel fails with `YOUTUBE_CHANNEL_REQUIRED`: create a channel in YouTube, then connect again, or choose another Google account. Multiple channels require a new authorization for the intended channel. Community publication is Coming soon. YouTube Analytics reports, thumbnails, playlists, comments, recurring schedules and paid ads are not included.

Private is the default visibility in ShipContent. Each upload sends the visibility that was approved, and YouTube decides the result. If YouTube returns another visibility, the saved result shows it with a note. OAuth verification is a separate requirement. Local checks do not establish provider approval or customer delivery.

Updated 2026-11-04. Google changed its upload rule. The [YouTube Data API revision history](https://developers.google.com/youtube/data/revision_history), entry of November 2, 2026, states: "Videos uploaded through the videos.insert method from unverified API projects are no longer restricted to private viewing mode." It also states: "This change reverses the policy announced on July 28, 2020". If a request does not specify `status.privacyStatus`, the video "defaults to public", and "Certain uploads might default to private based on creator account settings". ShipContent always sends this field. A public upload through ShipContent has not been tested.

The audit remains the route to extra quota. The [developer policies](https://developers.google.com/youtube/terms/developer-policies) state: "you can apply for a quota extension by completing an API Compliance Audit". The [upload method](https://developers.google.com/youtube/data/reference/rest/v3/videos/insert) lists a quota of "100 calls per day".

The saved channel name is read again with the saved token during upload work, and at most once a day when the owner opens the app. There is no scheduled cleanup. If Google refuses the saved token, ShipContent deletes the local connection data, cancels queued uploads, and shows "YouTube access was removed. Connect again to keep publishing." `get_youtube_status` then returns `pending.failureCode` `YOUTUBE_ACCESS_REVOKED`. The next connection saves the returned channel at once. Removed receipts become unknown; inspect YouTube Studio and do not upload again to recover a removed receipt.

Read the [ShipContent Privacy Policy](https://shipcontent.com/privacy), [ShipContent Terms](https://shipcontent.com/terms), [YouTube Terms of Service](https://www.youtube.com/t/terms) and [Google Privacy Policy](https://policies.google.com/privacy).

## Operator setup

Configure `YOUTUBE_CLIENT_ID` and `YOUTUBE_CLIENT_SECRET` for a separate channel OAuth client. Register `/integrations/youtube/callback` on the exact app origin. Enable the YouTube Data API and configure the consent screen and complete sensitive-scope verification. If its audience is Testing, only listed test users can connect and these offline refresh tokens expire after seven days. In production does not mean Google has approved the scopes. The requested channel scopes are youtube.readonly and youtube.upload, with offline access.

Set `SHIPCONTENT_YOUTUBE_VAULT_ACTIVE_KEY_ID` and `SHIPCONTENT_YOUTUBE_VAULT_KEYS` on the app and worker. Keep old keys while saved credentials refer to them. The app uses the existing restricted connection database login; the worker uses its restricted media database login. Apply the current database schema before enabling YouTube.

No customer supplies developer keys.

## Scheduled delivery

The owner checks the exact saved content and destination, then confirms its time in the [post editor](/docs/workflows/post-draft#automatic-schedules). An agent with Publish can save an automatic post schedule through `prepare_post_schedule`; otherwise the owner confirms the proposal. Updated 2026-11-19: the agent schedule uses the one connected channel of the workspace, so the owner does not select it for each post. Before this date, the schedule of a post that an agent made failed until the owner selected the channel. `publish_post` publishes an automatic post now through the same checks. For both tools, save the YouTube details on the post first: `create_post` and `edit_post` accept `youtube` with `title`, `description`, `privacyStatus`, `madeForKids` and `containsSyntheticMedia`. A post without a title returns `YOUTUBE_TITLE_REQUIRED`. Scheduled work uses the existing provider worker, current account/media checks and durable recovery. A planned date never publishes.

Updated 2026-10-28. Scheduled YouTube uploads are always available for a connected channel. No operator flag controls them. A linked job keeps its existing recovery path. See [scheduling errors](/docs/contracts/errors#scheduling-errors).

A schedule sets an upload start time. It promises no public release time and does not force Shorts classification. A schedule keeps the visibility the owner saved: Private, Unlisted or Public. YouTube decides the result and can return another visibility. Actual private and unlisted receipts stay **Uploaded · Private** and **Uploaded · Unlisted**. `YOUTUBE_NOT_CONFIGURED` needs operator action, not reconnect.

The [official upload reference](https://developers.google.com/youtube/data/reference/rest/v3/videos/insert), checked 2026-11-04, states: "Videos uploaded from unverified API projects are not restricted to private viewing mode." OAuth verification and API audit are separate. Neither is established by the local checks for this feature.
