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#
- Create a post draft and attach one saved MP4 video.
- Call
prepare_youtube_publicationwith thepostId. GivereviewUrlto the owner. - 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.
- 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.
- 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 anerrortext. See 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. 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.
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. To delete a video, use YouTube Studio. You can also request data deletion at 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 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.
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.
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, 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 state: "you can apply for a quota extension by completing an API Compliance Audit". The upload method 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, ShipContent Terms, YouTube Terms of Service and Google Privacy Policy.
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. 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.
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, 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.