Developer API
1. Overview
This API lets your own program schedule video uploads to a YouTube channel (chapters 1 to 8) and also post or schedule the same video and photos to SNS accounts: Instagram, Facebook, Threads, and TikTok (chapters 9 to 11). A YouTube upload works in three steps.
- Upload the file: Send the video (and a thumbnail, if you want one) to this service. Large files go up in pieces (chunks), and you can resume if the connection drops.
- Create a job: Send a manifest (JSON) with the uploaded file ids, title and description, visibility, and upload time.
- Check the status: When the scheduled time arrives, the service uploads the video to YouTube. You get the result (
video_id) from the job status or the event list.
All requests and responses are JSON (UTF-8). Timestamps are ISO-8601 with a time zone (for example 2026-10-20T09:00:00Z or 2026-10-20T18:00:00+09:00). The server stores times in UTC and returns them in UTC.
First, connect your channels and SNS accounts on the web. You can't connect an account through the API. Send every request over https.
2. Authentication and tokens
Create a token on the API tokens page and send it as a header with every request.
Authorization: Bearer ust_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
- The token is shown only once, when you create it. If you lose it, revoke it and create a new one.
- A token is valid for 90 days by default and 365 days at most. Each account can have up to 20 active tokens.
- A token works only with the account that created it and the channels that account has connected.
- Don't put tokens in your code or repository. Keep them in an environment variable or another secret store.
Permissions (scopes)
| Scope | What it allows |
|---|---|
uploads:write | Upload files (/uploads) |
jobs:read | View jobs, events, and the list of connected channels |
jobs:write | Create and cancel jobs |
jobs:publish | Put unlisted, public, and scheduled-public jobs in the queue immediately, without web confirmation (check it together with jobs:write) |
analytics:read | Read channel overview, recent videos, and stats |
social:read | Read the SNS account list, post status and performance, cards, the SNS rows of the schedule, and the SNS members of groups (chapter 9) |
social:write | Post, schedule, and cancel SNS posts, create photo posts (cards), and use the social field of POST /jobs (chapter 9, chapter 10) |
egress:read | Read the upload IPs assigned to you and the per-channel choices (8-1). Older tokens can also use jobs:read |
egress:write | Change a channel's upload IP (8-1). Not accepted with jobs:write (unlike reads, there is no legacy fallback) |
To see the status of SNS posts you create, check social:write and social:read together. The write scope doesn't include read.
A request without the needed scope returns 403 insufficient_scope. A wrong, expired, or revoked token returns 401 unauthorized.
3. Visibility
Set it with visibility.target in the manifest.
| Value | Meaning |
|---|---|
private | Private (default) |
unlisted | Unlisted (only people with the link) |
public | Public |
scheduled | Scheduled publish. The video is uploaded as private, then YouTube switches it to public at visibility.publish_at. |
Approve or interval publishing after a copyright-signal check (publish_gate)
When visibility.target is public, unlisted or scheduled, the video is by default uploaded as private first (even for scheduled the YouTube publishAt is never sent), and the service publishes it after checking the YouTube API signals. Optional field visibility.publish_gate: "auto" (default, server setting publish_gate_default) or "off" (upload as requested, as before). "off" is honored only in the web form; an "off" from an API request is treated as "auto" even with jobs:publish and the response warnings contain PUBLISH_GATE_OFF_IGNORED. private stays private with no gate. A job made while publishing is not yet allowed (the forced-private note above) also gets a gate: the upload stays forced private as today, and it is published only after publishing is allowed and the check passes (while it is off the gate just waits; it does not stall). Input validation, the web confirmation (awaiting_web_confirm) and the jobs:publish decision still use the requested value exactly as before.
- The first check runs 10 minutes after the upload completes, then every hour (
publish_gate_check_minutes), readingvideos.list(status,contentDetails,processingDetails). Right before publishing the video is always read once more. - Blocking signals:
uploadStatusofrejected,failedordeleted; arejectionReason(claim, copyright, legal, trademark, duplicate, ...); aregionRestriction;embeddable=falsethat the request did not ask for. Any one of them moves the gate toblockedimmediately and the video stays private. While the video is still processing the gate waits. An age restriction (ytAgeRestricted) is only recorded. - Publish conditions: at least 2 clean checks have made the video
ready(a candidate), the publish time has passed (the requestedpublish_at, or one hour after the upload completes), a person has approved it or the channel is set by a person to «publish every n hours», and the value just read isprivate. Nothing is published automatically just because it is clean (the default is publish after approval). If there are too few checks the publish moves to the next cycle, so it can be later than the scheduled time. - Limit: an ordinary channel cannot read Content ID claims on its own videos through the API (
claimSearchis for CMS partners only). Monetization or tracking-only claims may not show up as signals, so the name in responses is "no API copyright signal", not "no copyright issue". Studio internal APIs and cookies are not used. - Client note: a job with a gate can show
state: "uploaded"while the video is still private on YouTube untilpublish_gate.statebecomespublished.
Web confirmation and jobs:publish
If the token does not have jobs:publish, any non-private job is created with the state awaiting_web_confirm and is not uploaded. The account owner has to click “Confirm” in the job list on the web before the job moves to the queue (queued). This keeps a leaked token or a misbehaving script from suddenly making a video public.
To publish fully automatically with no human check, tick “Publish unlisted/public immediately (jobs:publish)” when you create the token. Jobs created with that token go straight to queued. Store a token with this scope with extra care.
Tokens issued through device approval below include jobs:publish when the “publish right away” checkbox on the approval page is ticked (it is ticked by default; untick it to leave it out). You can also turn instant publish on or off for that device token later on the web API tokens page.
4. Step 1: Upload the file
4-1. Open a slot
POST /api/v1/uploads
Content-Type: application/json
{"kind": "video", "content_type": "video/mp4", "size": 734003200,
"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"}
kind:video,thumbnail,caption(SRT or VTT subtitles) orimage(for SNS photo posts, chapter 10)content_type: for video,video/mp4,video/quicktime, orvideo/webm. For thumbnails,image/jpegorimage/png. For photos (image),image/jpegonlysize: total file size in bytes. Video up to 20 GiB, thumbnail up to 50 MiB (YouTube's own thumbnail limit is 2 MB, so stay under that), photo up to 4 MiBsha256: SHA-256 of the whole file (64 lowercase hex characters). Required.
Response 201:
{"upload_id": "up_0123456789abcdef01234567", "kind": "video", "content_type": "video/mp4",
"size": 734003200, "offset": 0, "state": "pending", "sha256": "e3b0…b855", "error_code": null,
"created_at": "…", "received_at": null, "deleted": false,
"chunk_size": 16777216, "max_chunk_size": 67108864}
4-2. Send the chunks
PUT /api/v1/uploads/{upload_id}
Content-Range: bytes 0-16777215/734003200
Content-Length: 16777216
(bytes 0–16777215 of the file)
- We recommend chunks of
chunk_size(16 MiB). The maximum ismax_chunk_size(64 MiB). Files of 64 MiB or less can be sent in one request. - The end value in
Content-Rangeis inclusive (bytes start-end/total). The start value must match exactly the number of bytes received so far (offset). - Response:
{"upload_id": "…", "offset": 16777216, "state": "receiving", "error_code": null, "verifying": false} - If the start value is off, you get
409 offset_mismatchalong with theoffsetthe server has. Resend from that value. - If the connection drops, resume from the
Upload-Offsetheader ofHEAD /api/v1/uploads/{upload_id}(or theoffsetfromGET). - If the start of the first chunk doesn't match the declared format (mp4, mov, webm, jpg, png), the request is rejected with
415 magic_mismatch.
4-3. Wait for verification
After the last chunk arrives, the server checks the SHA-256 and the format again. For files of 256 MiB or less, the response to the last PUT already has "state": "received". Larger files get "verifying": true and are verified in the background. Call GET /api/v1/uploads/{upload_id} every few seconds, and move on once state is received.
| state | Meaning |
|---|---|
pending | Slot opened, no bytes yet. It closes if nothing arrives within 1 hour. |
receiving | Receiving or verifying. It is discarded if no chunk arrives for 24 hours. |
received | Fully received and verified. You can use it in a job. |
failed | Failed. error_code: SHA256_MISMATCH, SIZE_MISMATCH, MAGIC_MISMATCH, DISK_ERROR, ABANDONED, and so on |
Files not used in a job are deleted after 48 hours. Files whose upload has finished are deleted once it's done. There is no API to download an uploaded file again.
5. Step 2: Schedule the upload
POST /api/v1/jobs
Content-Type: application/json
{
"schema_version": "upload-job/1.0",
"client_ref": "my-tool-2026-10-20-001",
"channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
"video": {"upload_id": "up_0123456789abcdef01234567",
"sha256": "e3b0…b855"},
"thumbnail": {"upload_id": "up_…", "sha256": "…"},
"metadata": {
"title": "Video title",
"description": "Description",
"tags": ["tag1", "tag2"],
"category_id": "22",
"default_language": "ko",
"self_declared_made_for_kids": false,
"contains_synthetic_media": false
},
"visibility": {"target": "scheduled", "publish_at": "2026-10-20T09:00:00Z"},
"notify_subscribers": true,
"not_before": "2026-10-20T08:00:00Z",
"upload_deadline": "2026-10-21T08:00:00Z",
"attestation": {
"actor_type": "human",
"approved_at": "2026-10-19T14:12:00Z",
"content_fingerprint": "e3b0…b855",
"source": "my-tool",
"approval_id": "review-1234"
}
}
Field reference
schema_version(required)- Always
"upload-job/1.0". client_ref(required)- A request name you choose (1 to 128 characters). If you send the same content again with the same value, no new job is created and the existing job is returned with
200. When a network drop leaves you unsure of the result, you can safely resend. The same value with different content returns409 client_ref_conflict. channel_id(required)- The YouTube channel ID to upload to (
UC…). It's thechannel_idfromGET /api/v1/channels. video(required)- The
upload_idandsha256(required) of a video file in thereceivedstate. If you includesizeandcontent_type, those are checked for a match too. The same video can't be scheduled again to the same channel while it has a live job there (409 video_already_scheduled), but it can go to a different channel. thumbnail(optional)- The thumbnail file. It has the same shape as
video. playlist_ids(optional)- Playlist IDs to add the video to after the upload finishes (at most 5, format
[A-Za-z0-9_-]{10,64}). A failure does not fail the upload; it is recorded in the job post_steps field as{"step","ok","code"}. If the channel connection lacks theyoutube.force-sslscope the code isscope_missing(quota cost 50). captions(optional)- Caption files (at most 3):
{"upload_id", "sha256", "language", "name" (up to 150 chars)}. The upload kind iscaption(SRT or VTT, up to 2 MiB;application/x-subrip,text/vttortext/plain) and the server checks the content minimally. They are sent after the upload succeeds and the files are then deleted (quota cost 400, result inpost_steps). metadata(required)-
titleis required, 100 characters or fewer.descriptionis 5000 bytes (UTF-8) or fewer.tagshas 60 items or fewer, 500 characters or fewer in total. Titles, descriptions, and tags can't contain<or>. If a limit is exceeded, the request is rejected with422 metadata_invalidinstead of being truncated, andreasonslists why.category_idis the YouTube category number (as a string), anddefault_languageis a language code (ko,en-US, and so on).license("youtube"or"creativeCommon"),embeddable,public_stats_viewableandhas_paid_product_placement(true/false),default_audio_language(language code),recording_date(YYYY-MM-DD) andlocalizations(per language code{"title": up to 100 chars, "description": up to 5000 bytes}, at most 20) are all optional; leaving them out keeps the current behavior.GET /api/v1/capabilitieslists the fields this server supports. You must setself_declared_made_for_kids(whether the video is made for kids) andcontains_synthetic_media(whether it contains AI-generated or altered content) to true or false. visibility(optional)- See Visibility. If omitted, it's
private. Forscheduled,publish_atis required and must be at least 15 minutes after both the current time andnot_before. notify_subscribers(optional)- Notify subscribers (default true).
not_before(optional)- Upload to YouTube no earlier than this time. If omitted, the upload starts right away.
upload_deadline(optional)- If the upload hasn't happened by this time, the job ends as
expired. The default and maximum is 14 days from now. social(optional)- Also post the same video to SNS accounts. Needs the
social:writescope; see 9-4 for the shape. attestation(required)- A record that a person reviewed this video and decided to upload it.
actor_typemust be"human",content_fingerprintmust equal the video's sha256, andapproved_at(when the person approved it) must be within the last 24 hours.sourceandapproval_idare optional notes for your own tool's records (128 characters or fewer).
Unknown fields are rejected with manifest_unknown_field (this catches typos).
Response
A new job returns 201. Resending the same client_ref returns 200. The body is a single job.
6. Step 3: Check the status
Get a job
GET /api/v1/jobs/{job_id}
GET /api/v1/jobs?state=queued&limit=100
limit is 1 to 500 (default 100), newest first. An unknown state returns 400 state_invalid; someone else's job returns 404 not_found.
Main fields: id, client_ref, state, visibility (the value that will actually be sent), requested_visibility, publish_at, not_before, upload_deadline, attempts, next_attempt_at, video_id, video_url, observed_status (the status YouTube reported), error_code, created_at, finished_at, manifest.
| state | Meaning |
|---|---|
awaiting_web_confirm | Waiting for confirmation on the web (chapter 3). Nothing is uploaded until it's confirmed. |
queued | Waiting in the queue. It uploads once not_before arrives. |
deferred | Postponed for now (daily limit or a temporary error). It retries at next_attempt_at. |
uploading | Sending to YouTube. |
uploaded | Done. video_id and video_url are filled in. |
failed | Failed (see error_code). To try again, upload the file again and create a new job. |
unknown | Sent, but the result couldn't be confirmed. To avoid duplicate uploads, it is not resent automatically. Check your channel, then contact us. |
expired | Couldn't upload before upload_deadline. |
canceled | Canceled. |
Events (change feed)
GET /api/v1/events?after=0&limit=100
{"events": [{"seq": 41, "job_id": "job_…", "type": "video.uploaded",
"payload": {"video_id": "…", "privacy_status": "public"}, "created_at": "…"}],
"next_after": 41}
Save the last next_after you received and pass it as after next time to get only new events (up to 500). Polling about once a minute is enough. Main type values: job.created, job.web_confirmed, job.rescheduled (the time was changed on the web), job.uploading, job.deferred, video.uploaded, thumbnail.set, thumbnail.failed, job.failed, job.unknown, job.expired, job.canceled, video.edited and video.deleted (the video was edited or deleted on the web), connection.needs_reauth (the channel must be reconnected), and connection.revoked. SNS events such as social.posted, social.rescheduled, social.needs_reauth, and social.revoked arrive in the same list. Ignore any type you don't know.
Auto-publish events: video.gate_blocked (a signal was found, payload.code), video.gate_published (published automatically), video.gate_stalled (processing delay or repeated publish failures; a person must release or cancel). video.visibility_changed is sent too when the video goes live.
7. Cancel a job
POST /api/v1/jobs/{job_id}/cancel
This works only before the job is sent to YouTube (queued, deferred, awaiting_web_confirm). Otherwise you get 409 job_not_cancelable. To remove a video that's already uploaded, delete it in YouTube Studio.
Publishing mode per channel, and approval. Every channel has a publishing mode. The default approval publishes only when a person approves, even after the check passes. interval, which a person must turn on in the accounts page, publishes videos that pass the check at least n hours (1-168) apart on that channel, without approval. There is no API to change the mode (only the web accounts page: «Edit» and «Apply the same mode to all YouTube channels»). Each channel in GET /api/v1/channels carries a read-only publish_policy: {"mode", "interval_hours"}. {"action": "approve"} approves publishing with a jobs:publish token (only in checking or ready, otherwise 409 publish_gate_not_approvable). Approving does not skip the signal checks or the re-check right before publishing. If a signal shows up after approval the video is not published and becomes blocked. New state ready (clean checks reached, a publish candidate) and new response fields approved_at, awaiting_approval, next_publish_at (expected time in interval mode), publish_mode, interval_hours and egress_fallback are added; existing fields are unchanged (capabilities.version 5). Canceling through the API (cancel) leaves CANCELED_VIA_API in block_code in every state, so visibility above keeps returning 409 visibility_gate_blocked (a cancel must not become a way around approval). A cancel by a person on the web page leaves no mark. The video.gate_published event carries via (approved, interval or released) and interval_hours, and a gate that waits for approval for more than 90 days becomes canceled (the video stays private) with a video.gate_expired event.
Copyright notice emails and «publish after the email check». Monetization and tracking-only Content ID claims are not in the YouTube API; they only arrive by email at the channel owner's Google account. The user forwards those emails with a Gmail filter to the receiving address shown on the accounts page, and a person confirms the source (Google account) with «Filter is set up» (no API can change it). The third publishing mode mail_checked publishes without approval only when the connection is email-confirmed and the video has zero claim emails. A video that gets a claim email is not published in any mode and becomes blocked (block_code CLAIM_MAIL, event video.gate_blocked with reason: claim_mail); an already published video only gets a video.claim_mail event. GET /api/v1/claims-mail?after=&limit= (jobs:read) returns my claim email records (id, received_at, subject, video_ids, source_email). Each channel in GET /api/v1/channels gains a read-only claims_mail_covered and the gate fields gain awaiting_reason (capabilities.version 7). Design: docs/specs/claims-mail.md in the repository.
When the fixed IP is unreachable. A channel with a fixed IP makes its check and publish calls through that IP. If it is blocked, the service waits 10 minutes and only then, if it is still blocked, goes through the server's default exit (an exception for the gate round only; uploads are still deferred). That the default exit was used is recorded in publish_gate.egress_fallback and the audit log.
POST /api/v1/jobs/{job_id}/visibility (jobs:publish)
Changes an uploaded private video (uploaded) to public or unlisted once, using a human-approval attestation. Body: {"target": "public", "attestation": {"actor_type": "human", "approval_id": "…", "approved_at": "…", "content_fingerprint": "video sha256"}}. The attestation's approval_id, approved_at and content_fingerprint must equal the approval recorded when the job was created (otherwise 409) and the approval must be under 24 hours old. It only works while the video is private on YouTube (409 visibility_not_private); before the Google app verification it returns 409 visibility_forced_private. Repeating the same request gives the same result (200 {"id", "visibility"}). Check support through job_actions (set_visibility) in GET /api/v1/capabilities, and read YouTube's verdict from video_status in GET /api/v1/jobs/{job_id} (privacy_status, upload_status, failure_reason, rejection_reason, region_restriction, claims; null when it cannot be read).
POST /api/v1/jobs/{job_id}/publish-gate (jobs:publish)
Operates the copyright-signal gate. {"action": "cancel"} ends the gate and keeps the video private (409 publish_gate_busy while a publish call is in progress; canceling a blocked or stalled gate is not allowed through the API: 403 publish_gate_cancel_web_only - a person does it on the web page). {"action": "reschedule", "publish_at": "2026-11-10T09:00:00Z"} changes the publish time only in the checking or ready state (moving the time of a video a person approved earlier is 409 publish_gate_approved_no_advance; delaying is allowed) (409 publish_gate_not_reschedulable). {"action": "release"} (lift a block or stall and publish) is not allowed through the API: 403 publish_gate_release_web_only; a person decides on the service web page. Calling the visibility endpoint above on a video whose gate is still checking (waiting_upload, checking, ready, publishing), blocked or stalled, or canceled after a block (block_code kept) returns 409 visibility_gate_blocked (no skipping the check, no way around a block). Videos without a gate, or with a finished gate, behave as before. Response {"id", "publish_gate"}. Check support via publish_gate in job_actions of GET /api/v1/capabilities (version 4 or later).
GET /api/v1/jobs/{job_id} and the list response gain a publish_gate field (null when there is no gate): state (waiting_upload, checking, ready, publishing, published, published_external, blocked, stalled, canceled), final_target, publish_at, next_check_at, last_check_at, checks, clean_checks, block_code, signal (the last signals read) and note (the limit sentence above).
POST /api/v1/jobs/{job_id}/thumbnail (jobs:publish)
Replaces the thumbnail of an already uploaded video (uploaded) using a human-approval attestation. Body: {"thumbnail": {"upload_id": "up_…", "sha256": "…"}, "attestation": {"actor_type": "human", "approval_id": "…", "approved_at": "…"}}. The image is the upload_id/sha256 of a file uploaded first with kind=thumbnail (JPEG or PNG, up to 2 MB, at least 640x360, roughly 16:9). The attestation's approval_id and approved_at must match the approval given when the job was created (otherwise 409), and the approval must be within 24 hours after the upload finished (attestation_stale). One job accepts up to 3 different images (A/B/C) under the same approval (more gives 409 thumbnail_limit); using the same approval for another job's thumbnail or visibility gives 409 attestation_approval_reused (visibility and thumbnail changes on the same job do not block each other). Sending an image the job already has returns 200 {"id", "thumbnail": {"sha256"}, "idempotent": true} without calling YouTube. After a failure, retries get 429 thumbnail_retry_later for 10 minutes. It costs 50 quota units. Check support via set_thumbnail in job_actions of GET /api/v1/capabilities.
8. Read channels and stats
GET /api/v1/channels (jobs:read)
Lists your connected channels: id (connection id, yc_…), channel_id (UC…), channel_title, label, state (active, needs_reauth, revoked), and more. Jobs use channel_id. The stats endpoints below use the connection id.
GET /api/v1/channels/{connection id}/overview (analytics:read)
GET /api/v1/channels/{connection id}/videos?max_results=20&page_token=…
GET /api/v1/channels/{connection id}/analytics?metrics=views,likes&dimensions=day&start=2026-09-01&end=2026-09-30
GET /api/v1/channels/{connection id}/reports
videos:max_resultsis 1 to 50.- Optional fields on each
videositem (nullwhen unavailable, with the reason in the responseperf_unavailable;fillingmeans the server is still filling its cache, so call the list again - at most 2 external calls per request):views_48h(views summed over the publish day plus two days; Analytics is per day, so this approximates 48 hours, available from 3 days after publishing),impressionsandctr(thumbnail impressions and click-through rate in %, from the YouTube Reporting APIchannel_reach_basic_a1; only for channels where reports were turned on in the analytics page, summed over up to 7 daily reports, period inreach_window). analytics: choosemetricsfromviews,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained,subscribersLost,likes,comments,shares,viewerPercentage. Choosedimensionsfromday,video,insightTrafficSourceType,ageGroup,gender,country,deviceType. The date range is 365 days at most, and defaults to the last 28 days.- For
analytics,startandendareYYYY-MM-DD(the end date is today at the latest),dimensionstakes at most 2 values,sortis one of the chosen metric or dimension names (prefix-for descending), andmax_resultsis 1 to 200. Thevideodimension requires bothsortandmax_results(400 video_dimension_needs_sort). - Error codes of the stats API: 400
metric_not_allowed,dimension_not_allowed,sort_not_allowed,date_invalid,period_too_long,invalid_max_results,invalid_page_token,query_rejected; 403scope_missing(reconnect the channel and allow the permission) andyoutube_forbidden; 404channel_not_foundandnot_found_at_youtube; 409channel_mismatchandconnection_not_active; 429quota_limit(the daily read limit or the YouTube quota was exceeded); 502youtube_error,youtube_unavailable,report_too_large,report_url_rejected; 503not_configuredandegress_unavailable(the channel's static IP cannot be used right now - the server's default IP is never used instead). The body has the same shape.
8-1. Upload IP (Korean static IP)
If the admin has assigned you a Korean static IP, you can decide per channel whether it uploads through that IP (the same as "Upload IP" on the web Accounts page). If none is assigned, ips is empty and every channel uploads through the server's default egress. Once a channel has an IP, all its Google traffic (token refresh, upload, follow-up steps) leaves through that IP only; if the tunnel is down the job is never sent through the server's default IP and is postponed as deferred (error_code EGRESS_UNAVAILABLE), rechecked every 10 minutes.
GET /api/v1/egress (egress:read or jobs:read)
PUT /api/v1/egress/channels/{connection_id} (egress:write)
curl -s "$BASE/egress" -H "Authorization: Bearer $TOOLULAH_TOKEN"
{"ips": [{"id": "eg_0123456789abcdef01234567", "label": "Seoul 1", "ip": "121.126.246.62",
"up": true, "checked_at": "2026-11-02T01:02:00Z", "enabled": true}],
"channels": [{"connection_id": "yc_…", "channel_id": "UC…", "title": "My channel", "alias": "Main",
"egress_ip_id": "eg_0123456789abcdef01234567"}]}
curl -s -X PUT "$BASE/egress/channels/yc_…" -H "Authorization: Bearer $TOOLULAH_TOKEN" \
-H "Content-Type: application/json" -d '{"egress_ip_id": null}'
ipslists only the IPs assigned to you.upis the tunnel state (trueconnected,falsedown,nullunknown);checked_atis when that state was checked.channelsare your live YouTube connections;egress_ip_idnullmeans the default (server) egress.titleis the channel name andaliasis the label you gave it.- The
PUTbody is exactly{"egress_ip_id": "eg_…"}or{"egress_ip_id": null}(back to default); the response is the one updatedchannelsitem. It applies from the next upload. - Errors:
403 egress_ip_not_assigned(not your IP - an unknown id gets the same answer),409 egress_ip_disabled(turned off by the admin),404 not_found(missing, someone else's, or disconnected connection). - Tokens created earlier keep working for
GETwithjobs:read.PUTrequiresegress:writeand is not accepted withjobs:write(the operator grants the new scopes to older device tokens). Registering, assigning, and deleting static IPs is admin-only.
10. Photo posts (card news)
Schedule text plus several photos at once as an Instagram carousel, a Threads post, a Facebook Page post, and a TikTok photo post. You need social:write (to create) and social:read (to look up), and uploads:write to upload the photos.
10-1. Upload the photos
Same as chapter 4, with kind set to image. Only image/jpeg is accepted, each photo is up to 4 MiB, and you can send it in one request. The server checks that the JPEG is intact and replaces it with a copy without EXIF, GPS, or other metadata. So the sha256 you see from GET /uploads/{upload_id} after verification can differ from the one you declared (the card request only uses the upload_id, so this doesn't matter). One photo takes one upload slot, and opening slots is limited to 30 per hour (Limits).
curl -s -X POST "$BASE/uploads" -H "Authorization: Bearer $TOOLULAH_TOKEN" -H "Content-Type: application/json" \
-d '{"kind": "image", "content_type": "image/jpeg", "size": 183402, "sha256": "…"}'
10-2. Create a card
POST /api/v1/cards (social:write)
curl -s -X POST "$BASE/cards" -H "Authorization: Bearer $TOOLULAH_TOKEN" -H "Content-Type: application/json" \
-d '{
"client_ref": "my-tool-card-001",
"body": "Daily card news #info",
"images": ["up_aaaaaaaaaaaaaaaaaaaaaaaa", "up_bbbbbbbbbbbbbbbbbbbbbbbb"],
"not_before": "2026-10-20T09:00:00Z",
"tiktok_title": "Card news title",
"targets": [
{"connection_id": "sc_aaaaaaaaaaaaaaaaaaaaaaaa"},
{"connection_id": "sc_cccccccccccccccccccccccc", "tiktok": {"privacy_level": "SELF_ONLY", "allow_comment": true}}
]
}'
client_ref(required)- 1 to 128 characters. The same value with the same request (text, photo order, target accounts, times, TikTok options) returns the existing card with
200(before any check, so TikTok is not queried again); anything different returns409 client_ref_conflict. body- The text. Limits: 2,200 characters for Instagram and Facebook, 500 for Threads, 4,000 for TikTok (counted in UTF-16), and 10,000 for any platform.
images(required, may be empty)- An empty list
[]makes a text-only post. Then only Threads and Facebook Pages can be targets (Instagram/TikTok givecards.error.TEXT_ONLY_PLATFORM) andbodyis required (no photos and no body givescards.error.NO_IMAGES). Photoupload_ids in the order to show them. Only your own,received, JPEG photos work (otherwisecards.error.IMAGE_UNAVAILABLE), with no duplicates. Maximum per card: Instagram 10, Facebook 10, Threads 20, TikTok 35 (the smallest limit among the chosen platforms). not_before·targets- Same as 9-3. For photo posts the TikTok options are only
privacy_level,allow_comment, andcommercial; passingallow_duetorallow_stitchis rejected withapi.social.tiktok_photo_option. tiktok_title(optional)- Used only when TikTok is chosen. At most 90 characters (UTF-16), one line. If empty, the first line of the text.
Response 201/200:
{"id": "cd_…", "body": "…", "tiktok_title": null, "image_count": 2,
"images": [{"position": 0, "upload_id": "up_…", "width": 1080, "height": 1350, "deleted": false}],
"not_before": "…", "deadline": "…", "created_at": "…", "canceled_at": null,
"posts": [{"id": "sp_…", "kind": "photo", "platform": "instagram", "card_id": "cd_…", "state": "queued", …}]}
A photo post needs at least one photo. One card creates one post per platform; status, performance, and cancellation use the post API from chapter 9 (/social/posts/{post_id}). A card's photos are deleted when its retention period ends.
10-3. Get a card
GET /api/v1/cards/{card_id} (social:read)
curl -s "$BASE/cards/cd_0123456789abcdef01234567" -H "Authorization: Bearer $TOOLULAH_TOKEN"
Same shape as the 10-2 response. Someone else's card returns 404 not_found. There is no API to download a card's photo files (only the web detail page).
11. Schedule
GET /api/v1/schedule?from=2026-10-20T00:00:00Z&to=2026-10-27T00:00:00Z (jobs:read)
curl -s "$BASE/schedule?from=2026-10-20T00:00:00Z&to=2026-10-27T00:00:00Z" -H "Authorization: Bearer $TOOLULAH_TOKEN"
{"entries": [{"type": "upload", "id": "job_…", "platform": "youtube", "connection_id": "yc_…",
"account": "My channel", "title": "Video title", "state": "queued", "at": "2026-10-20T08:00:00.000000Z",
"publish_at": "2026-10-20T09:00:00.000000Z", "error_code": null, "video_url": null, "cancelable": true},
{"type": "card", "id": "sp_…", "platform": "threads", "connection_id": "sc_…", "account": "@me",
"title": "Today's card news", "state": "queued", "at": "…", "publish_at": null, "error_code": null,
"video_url": null, "cancelable": true}]}
- The same combined list as the Schedule page, in time order (
at). Only things that haven't finished appear: waiting or running YouTube uploads, YouTube scheduled-public times, SNS video posts, and photo posts. type:upload(YouTube upload,id= job id),publish(the YouTube scheduled-public time; the same job can also appear asupload),sns(video post),card(photo post). For SNS rows,idis the post id (sp_…).atis when the thing happens.from(inclusive) andto(exclusive) are ISO-8601 with a time zone, and both are optional. You can look at up to 90 days at a time: giving both beyond 90 days returns400 invalid_request, and omittingtomeans 90 days fromfrom(or from now).limitis 1 to 500 (default 200); if there are more,"truncated": trueis returned, so narrow the window and call again. Thetoin the response is the end time actually applied. A bad value returns400 invalid_request.- When
cancelableis true, cancel a YouTube row withPOST /jobs/{job_id}/canceland an SNS or card row withPOST /social/posts/{post_id}/cancel. Changing a time is web-only. - SNS and card rows appear only if the token also has
social:read(with onlyjobs:readyou get the YouTube rows). - Up to 2,000 YouTube jobs and 2,000 SNS posts are read. Other people's schedule never appears.
12. Connect a tool (device approval)
If you build an upload tool for other people, you can let users connect it by entering a code instead of copying and pasting a token (RFC 8628 flow).
POST /api/v1/device/authorize (no auth)
{"client_name": "My Upload Tool"}
→ {"device_code": "…", "user_code": "ABCD-EFGH", "expires_in": 600, "interval": 5,
"verification_uri": "https://upload.toolulah.com/link",
"verification_uri_complete": "https://upload.toolulah.com/link?code=ABCD-EFGH"}
- Show the user the
user_codeand theverification_uri. The user signs in, enters the code, and clicks “Approve”. - Your tool asks for the token every
interval(5 seconds).POST /api/v1/device/token {"device_code": "…"}While waiting you get{"error": "authorization_pending"}. Polling too often returnsslow_down, a denial returnsaccess_denied, and after 10 minutes you getexpired_token. - Once approved, you get
{"access_token": "ust_…", "scopes": [...], "expires_at": "…", "username": "…"}exactly once. It's valid for 90 days, and its scopes areuploads:write jobs:read jobs:write analytics:read social:read social:write egress:read egress:write, plusjobs:publishwhen the approval-page checkbox is ticked (it is ticked by default; untick it to leave it out, and you can turn it on or off later on the web API tokens page). - To disconnect, have the token revoke itself with
POST /api/v1/tokens/self/revoke.
13. Limits
- API requests: 120 per minute per user (tokens are counted together, even if you create several).
- Creating SNS posts and cards (
POST /social/posts,POST /cards, andPOST /jobswithsocial) and canceling a post (POST /social/posts/{post_id}/cancel): 30 per minute per user (also counted in the 120 above). One card photo uses one upload slot. - Opening upload slots: 30 per hour per user. Up to 3 files receiving at the same time. Chunk PUTs: 120 per minute per token.
- Video 20 GiB, thumbnail 50 MiB, photo 4 MiB, chunk 64 MiB, manifest or SNS request body 256 KB. Up to 30 SNS targets per request.
- When you exceed a limit, you get
429with aRetry-Afterheader (in seconds). Wait that long, then resend.
14. Errors
Every error body has the same shape. code is a lowercase English value for programs to read, and message is a human-readable sentence (in the request language). Errors that can have several causes (metadata_invalid, social_invalid, card_invalid) add a reasons array.
{"code": "metadata_invalid", "message": "…", "reasons": ["TITLE_INVALID", "MADE_FOR_KIDS_UNSET"]}
{"code": "social_invalid", "message": "…", "reasons": ["social.error.caption_too_long_threads", "api.social.target_duplicate"]}
The reasons items of social_invalid and card_invalid are either the same message keys the web form uses (social.error.*, cards.error.*, web.error.schedule_*, schedule.error.target_*) or API shape errors (api.social.*, api.cards.*). All problems are listed at once, so fix them together.
api.social.invalid: an unknown key, or not an object ·api.social.targets_invalid:targetsis missing, empty, or has more than 30 items ·api.social.target_invalid: a target item has the wrong shape ·api.social.target_duplicate: the same account chosen twicesocial.error.target_unavailable: an unknown, someone else's, or disconnected account ·api.social.not_before_invalid: not an ISO-8601 time with a time zone ·api.social.caption_requiredandapi.social.caption_invalid·api.social.share_to_feed_invalidapi.social.tiktok_invalid: the TikTok options have the wrong shape ·api.social.tiktok_not_allowed:tiktokgiven for a non-TikTok account ·api.social.tiktok_photo_option: duet or stitch given for a photo post ·api.cards.images_invalidandapi.cards.body_invalid- Same rules as the web:
social.error.caption_too_long_{instagram|facebook|threads|tiktok},social.error.video_type,social.error.video_too_large_*,social.error.duration_*,social.error.tiktok_privacy_required,tiktok_commercial_choose,tiktok_branded_private,tiktok_cannot_post,cards.error.NO_IMAGES,IMAGE_UNAVAILABLE,IMAGE_DUPLICATE,IMAGES_TOO_MANY_*,BODY_TOO_LONG_*,web.error.schedule_past,schedule_too_far,schedule_invalid
| HTTP | Common codes |
|---|---|
| 400 | invalid_request (including bad queries, cursors, and JSON), manifest_invalid, bad_content_range, length_mismatch, sha256_required, invalid_sha256, state_invalid |
| 401 | unauthorized |
| 403 | insufficient_scope, consent_required (you must accept the updated terms on the web), password_change_required, attestation_not_human |
| 404 | not_found (missing or someone else's — jobs, posts, cards, and uploads all answer the same), video_upload_not_found, thumbnail_upload_not_found |
| 408 | timeout (no chunk body for 60 seconds — resend that chunk) |
| 409 | offset_mismatch, chunk_in_progress (a chunk of the same file is still being handled), upload_closed, client_ref_conflict, video_not_received, video_not_ready, video_sha256_mismatch, video_size_mismatch, video_content_type_mismatch (and the same thumbnail_*), video_already_scheduled, thumbnail_already_scheduled, attestation_fingerprint_mismatch, job_not_cancelable, post_not_cancelable |
| 413 / 415 | too_large, chunk_too_large / unsupported_type, magic_mismatch |
| 422 | Manifest rule violations: metadata_invalid (+reasons), channel_not_connected, channel_id_invalid, client_ref_invalid, schema_version_unsupported, manifest_unknown_field, video_required, video_sha256_invalid (and the same thumbnail_*), visibility_invalid, publish_at_invalid, publish_at_not_allowed, schedule_time_required, schedule_in_past_or_too_soon, schedule_before_upload, notify_subscribers_invalid, not_before_invalid, upload_deadline_invalid, upload_deadline_too_far, attestation_required, attestation_invalid, attestation_approved_at_required, attestation_stale (approval is more than 24 hours old)SNS: social_invalid (+reasons), card_invalid (+reasons) |
| 429 | rate_limited, too_many_active, too_many_failures |
| 500 / 507 | disk_error, server_error / user_storage_full, storage_full |
If you send a wrong token too many times, that IP is blocked for a short while (429 too_many_failures).
15. Full example (Python)
It uses only requests. Put your token in the TOOLULAH_TOKEN environment variable.
import hashlib
import os
import time
from datetime import datetime, timedelta, timezone
import requests
BASE = "https://upload.toolulah.com/api/v1"
H = {"Authorization": "Bearer " + os.environ["TOOLULAH_TOKEN"]}
VIDEO = "video.mp4"
def sha256_of(path):
h = hashlib.sha256()
with open(path, "rb") as f:
for block in iter(lambda: f.read(1024 * 1024), b""):
h.update(block)
return h.hexdigest()
def upload(path, kind, content_type):
size, digest = os.path.getsize(path), sha256_of(path)
r = requests.post(f"{BASE}/uploads", headers=H, timeout=30,
json={"kind": kind, "content_type": content_type, "size": size, "sha256": digest})
r.raise_for_status()
up = r.json()
offset, chunk = up["offset"], up["chunk_size"]
with open(path, "rb") as f:
while offset < size:
f.seek(offset)
data = f.read(chunk)
rng = f"bytes {offset}-{offset + len(data) - 1}/{size}"
r = requests.put(f"{BASE}/uploads/{up['upload_id']}", data=data, timeout=300,
headers={**H, "Content-Range": rng, "Content-Type": "application/octet-stream"})
if r.status_code == 409 and r.json().get("code") == "offset_mismatch":
offset = r.json()["offset"] # resend from the position the server has
continue
r.raise_for_status()
offset = r.json()["offset"]
while True: # wait for server verification (sha256, format)
state = requests.get(f"{BASE}/uploads/{up['upload_id']}", headers=H, timeout=30).json()
if state["state"] == "received":
return up["upload_id"], digest
if state["state"] == "failed":
raise RuntimeError(state["error_code"])
time.sleep(5)
def iso(dt):
return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
channel = requests.get(f"{BASE}/channels", headers=H, timeout=30).json()["channels"][0]["channel_id"]
upload_id, digest = upload(VIDEO, "video", "video/mp4")
now = datetime.now(timezone.utc)
manifest = {
"schema_version": "upload-job/1.0",
"client_ref": "demo-" + digest[:16],
"channel_id": channel,
"video": {"upload_id": upload_id, "sha256": digest},
"metadata": {"title": "Uploaded via API", "description": "", "tags": [],
"self_declared_made_for_kids": False, "contains_synthetic_media": False},
"visibility": {"target": "unlisted"},
"attestation": {"actor_type": "human", "approved_at": iso(now), "content_fingerprint": digest,
"source": "demo-script"},
}
r = requests.post(f"{BASE}/jobs", headers=H, json=manifest, timeout=30)
r.raise_for_status()
job = r.json()
print(job["id"], job["state"]) # queued with jobs:publish, awaiting_web_confirm without it
while job["state"] not in ("uploaded", "failed", "unknown", "expired", "canceled"):
time.sleep(30)
job = requests.get(f"{BASE}/jobs/{job['id']}", headers=H, timeout=30).json()
print(job["state"], job.get("video_url"))
If you have questions or run into problems, let us know at support@toolulah.com. For general usage, see the Help page.
9. SNS posting (Instagram · Facebook · Threads · TikTok)
Publish or schedule an uploaded video to SNS accounts, instead of or together with YouTube. Connect the SNS accounts first on the web (Connect accounts); the API can't connect or disconnect them. The APIs in this chapter need the
social:readandsocial:writescopes (chapter 2). In the examples,$BASEishttps://upload.toolulah.com/api/v1and$TOOLULAH_TOKENis your token.9-1. Connected SNS accounts
curl -s "$BASE/social/connections" -H "Authorization: Bearer $TOOLULAH_TOKEN" {"connections": [{"id": "sc_0123456789abcdef01234567", "platform": "instagram", "account_name": "@my_account", "label": "Main", "display_name": "@my_account · Main", "state": "active", "last_error_code": null, "authorized_at": "…", "capabilities": {"post": true, "insights": true, "messages": false}}]}platform:instagram,facebook,threads,tiktok.state:active(can post) orneeds_reauth(reconnect on the web). Disconnected accounts are not listed.capabilities:postcan publish,insightshas permission to read metrics,messageshas the inbox permission.id(sc_…) to post.9-2. Channel groups
curl -s "$BASE/groups" -H "Authorization: Bearer $TOOLULAH_TOKEN" {"groups": [{"id": "tg_…", "name": "All shorts", "created_at": "…", "updated_at": "…", "members": [{"kind": "youtube", "connection_id": "yc_…", "platform": "youtube", "name": "My channel", "alive": true}, {"kind": "social", "connection_id": "sc_…", "platform": "threads", "name": "@me", "alive": true}]}]}A group is just a named selection; the server doesn't "run" a group. Pick the members'
connection_idvalues and use them aschannel_id(chapter 8) or SNStargets. A token with onlyjobs:readsees the YouTube members, and one with onlysocial:readsees the SNS members. Creating, editing, and deleting groups is web-only.9-3. Post or schedule a video to SNS
curl -s -X POST "$BASE/social/posts" \ -H "Authorization: Bearer $TOOLULAH_TOKEN" -H "Content-Type: application/json" \ -d '{ "client_ref": "my-tool-2026-10-20-sns-001", "video": {"upload_id": "up_0123456789abcdef01234567", "sha256": "e3b0…b855"}, "caption": "New video is up #shorts", "share_to_feed": true, "not_before": "2026-10-20T09:00:00Z", "targets": [ {"connection_id": "sc_aaaaaaaaaaaaaaaaaaaaaaaa"}, {"connection_id": "sc_bbbbbbbbbbbbbbbbbbbbbbbb", "not_before": "2026-10-20T12:00:00Z"}, {"connection_id": "sc_cccccccccccccccccccccccc", "tiktok": {"privacy_level": "SELF_ONLY", "allow_comment": true, "allow_duet": false, "allow_stitch": false, "commercial": {"brand_organic": false, "brand_content": false}}} ] }'client_ref(required)video(required)upload_idandsha256(both required) of a video in thereceivedstate. Only MP4 and MOV work (no WebM). Someone else's file or a missing one returns404 video_upload_not_found; a file that isn't fully received returns409 video_not_received.caption(required)share_to_feed(optional, default true)not_before(optional)targets(required, 1 to 30)connection_id(required, no duplicates),not_before(optional, a different time for just this account), andtiktok(TikTok accounts only). An account that isn't yours or is disconnected always givessocial.error.target_unavailable, without saying whether it exists.TikTok options (same rules as the web)
privacy_levelis required and has no default. It must be one ofPUBLIC_TO_EVERYONE,MUTUAL_FOLLOW_FRIENDS,FOLLOWER_OF_CREATOR,SELF_ONLYthat this TikTok account currently allows (the server asks TikTok, only for the TikTok accounts you chose in the request, and reuses the answer from server memory for up to 90 seconds — if TikTok changes the allowed values in that time, the request may be checked against the earlier values).allow_comment,allow_duet,allow_stitch: off by default. An option the creator has turned off stays off even if you set it.commercial: commercial content disclosure. An object (ortrue) turns it on, and then at least one ofbrand_organic(your own brand) orbrand_content(branded content) must be true. Branded content can't be posted asSELF_ONLY.Response
201(created) or200(the same request sent again):{"batch_id": "bt_…", "created": true, "posts": [{"id": "sp_…", "kind": "video", "platform": "threads", "connection_id": "sc_…", "account_name": "@me", "state": "queued", "job_id": null, "card_id": null, "batch_id": "bt_…", "caption": "…", "not_before": "…", "deadline": "…", "attempts": 0, "next_attempt_at": null, "error_code": null, "permalink": null, "created_at": "…", "finished_at": null, "remote_deleted": false, "performance": null}]}Idempotency: sending the same
client_refwith the same request (same video, caption,share_to_feed,not_before, per-account times, and TikTok options) again doesn't create anything new and returns the existing posts with200. Only notation differences (JSON key order, omitted defaults, time zone spelling) still count as the same request. The sameclient_refwith anything different returns409 client_ref_conflict. Canceled posts still count as existing. If you cancel everything and resend the same request, nothing new is posted; you get the existing (canceled) posts with200. Use a newclient_refto post again. Sending the same video to an account that still has a live post for it, under a differentclient_ref, returns409 video_already_scheduled.If validation fails you get
422 social_invalidwith every problem inreasons(see Errors), and nothing is created.9-4. Post together with a YouTube job (
socialinPOST /jobs)Add the optional field
socialto the manifest of a YouTube upload job (chapter 5) and the SNS posts are created in the same batch for the same video (like "Also post to SNS" on the web). The token needs bothjobs:writeandsocial:write; otherwise403 insufficient_scope. Withoutsocial(or withnull) nothing changes.curl -s -X POST "$BASE/jobs" -H "Authorization: Bearer $TOOLULAH_TOKEN" -H "Content-Type: application/json" \ -d '{ "schema_version": "upload-job/1.0", "client_ref": "…", "channel_id": "UC…", "video": {…}, "metadata": {…}, "attestation": {…}, "social": {"caption": "(optional)", "share_to_feed": true, "targets": [{"connection_id": "sc_…"}, {"connection_id": "sc_…", "not_before": "2026-10-20T12:00:00Z"}]}}'socialare the same ascaption,share_to_feed, andtargetsin 9-3. If you leavecaptionempty, the text istitle + blank line + description.not_beforeto change just that account.422 social_invalidand no job is created."social_posts"array (the post shape from 9-3). Resending the sameclient_ref(200) returns the posts that already exist, and adds"social_ignored": trueto show that this request'ssocialwas not looked at (different content is ignored, not a 409 — send a newclient_refto change it). The field is absent on the first creation.9-5. Post status and performance
GET /api/v1/social/posts?state=&job_id=&limit=50&after=sp_… (social:read) GET /api/v1/social/posts/{post_id} (social:read)curl -s "$BASE/social/posts?state=posted&limit=20" -H "Authorization: Bearer $TOOLULAH_TOKEN" {"posts": [{"id": "sp_…", "state": "posted", "permalink": "https://www.threads.net/…", "error_code": null, "performance": {"state": "ok", "metrics": {"views": 120, "likes": 8}, "fetched_at": "…"}, …}], "next_after": null}limitis 1 to 200 (default 50). For the next page pass the response'snext_afterasafter(nullmeans the end). Filter bystateand byjob_id(the batch from 9-4). An unknownstatereturns400 state_invalid; a badafterreturns400 invalid_request.404 not_found.permalinkis present only when it is anhttpsaddress.error_codeis the reason code when the state isfailed,deferred, orunknown.performanceexists only forpostedposts. Itsstateisok(numbers such as views and likes inmetrics),pending(not read yet),need_scope(the account hasn't granted metrics permission — reconnect on the web), orerror. Metric names differ by platform.queuednot_beforearrives. It can be canceled only in this state (anddeferred).deferrednext_attempt_at. Can be canceled.sending·processingpostedpermalinkmay be filled in.failederror_code). It isn't sent again automatically; create a new one.unknownexpireddeadline.canceled9-6. Cancel a post
POST /api/v1/social/posts/{post_id}/cancel (social:write)Only a post that hasn't started sending (
queuedordeferred) is canceled, and the updated post is returned. Any other state returns409 post_not_cancelable; someone else's post returns404.9-7. Web-only actions
These need re-authentication or a person's confirmation, so they are not in the API: connecting, disconnecting, and labeling SNS accounts; editing or deleting a post that is already published; changing a schedule time; creating, editing, and deleting channel groups; comment auto-reply rules; and the inbox.