Developer API

toolulah Upload · REST API v1 · https://upload.toolulah.com/api/v1

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.

  1. 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.
  2. Create a job: Send a manifest (JSON) with the uploaded file ids, title and description, visibility, and upload time.
  3. 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)

ScopeWhat it allows
uploads:writeUpload files (/uploads)
jobs:readView jobs, events, and the list of connected channels
jobs:writeCreate and cancel jobs
jobs:publishPut unlisted, public, and scheduled-public jobs in the queue immediately, without web confirmation (check it together with jobs:write)
analytics:readRead channel overview, recent videos, and stats
social:readRead the SNS account list, post status and performance, cards, the SNS rows of the schedule, and the SNS members of groups (chapter 9)
social:writePost, schedule, and cancel SNS posts, create photo posts (cards), and use the social field of POST /jobs (chapter 9, chapter 10)
egress:readRead the upload IPs assigned to you and the per-channel choices (8-1). Older tokens can also use jobs:read
egress:writeChange 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.

ValueMeaning
privatePrivate (default)
unlistedUnlisted (only people with the link)
publicPublic
scheduledScheduled 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), reading videos.list (status, contentDetails, processingDetails). Right before publishing the video is always read once more.
  • Blocking signals: uploadStatus of rejected, failed or deleted; a rejectionReason (claim, copyright, legal, trademark, duplicate, ...); a regionRestriction; embeddable=false that the request did not ask for. Any one of them moves the gate to blocked immediately 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 requested publish_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 is private. 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 (claimSearch is 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 until publish_gate.state becomes published.

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) or image (for SNS photo posts, chapter 10)
  • content_type: for video, video/mp4, video/quicktime, or video/webm. For thumbnails, image/jpeg or image/png. For photos (image), image/jpeg only
  • size: 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 MiB
  • sha256: 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 is max_chunk_size (64 MiB). Files of 64 MiB or less can be sent in one request.
  • The end value in Content-Range is 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_mismatch along with the offset the server has. Resend from that value.
  • If the connection drops, resume from the Upload-Offset header of HEAD /api/v1/uploads/{upload_id} (or the offset from GET).
  • 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.

stateMeaning
pendingSlot opened, no bytes yet. It closes if nothing arrives within 1 hour.
receivingReceiving or verifying. It is discarded if no chunk arrives for 24 hours.
receivedFully received and verified. You can use it in a job.
failedFailed. 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 returns 409 client_ref_conflict.
channel_id (required)
The YouTube channel ID to upload to (UC…). It's the channel_id from GET /api/v1/channels.
video (required)
The upload_id and sha256 (required) of a video file in the received state. If you include size and content_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 the youtube.force-ssl scope the code is scope_missing (quota cost 50).
captions (optional)
Caption files (at most 3): {"upload_id", "sha256", "language", "name" (up to 150 chars)}. The upload kind is caption (SRT or VTT, up to 2 MiB; application/x-subrip, text/vtt or text/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 in post_steps).
metadata (required)
title is required, 100 characters or fewer. description is 5000 bytes (UTF-8) or fewer. tags has 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 with 422 metadata_invalid instead of being truncated, and reasons lists why. category_id is the YouTube category number (as a string), and default_language is a language code (ko, en-US, and so on). license ("youtube" or "creativeCommon"), embeddable, public_stats_viewable and has_paid_product_placement (true/false), default_audio_language (language code), recording_date (YYYY-MM-DD) and localizations (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/capabilities lists the fields this server supports. You must set self_declared_made_for_kids (whether the video is made for kids) and contains_synthetic_media (whether it contains AI-generated or altered content) to true or false.
visibility (optional)
See Visibility. If omitted, it's private. For scheduled, publish_at is required and must be at least 15 minutes after both the current time and not_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:write scope; see 9-4 for the shape.
attestation (required)
A record that a person reviewed this video and decided to upload it. actor_type must be "human", content_fingerprint must equal the video's sha256, and approved_at (when the person approved it) must be within the last 24 hours. source and approval_id are 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.

stateMeaning
awaiting_web_confirmWaiting for confirmation on the web (chapter 3). Nothing is uploaded until it's confirmed.
queuedWaiting in the queue. It uploads once not_before arrives.
deferredPostponed for now (daily limit or a temporary error). It retries at next_attempt_at.
uploadingSending to YouTube.
uploadedDone. video_id and video_url are filled in.
failedFailed (see error_code). To try again, upload the file again and create a new job.
unknownSent, but the result couldn't be confirmed. To avoid duplicate uploads, it is not resent automatically. Check your channel, then contact us.
expiredCouldn't upload before upload_deadline.
canceledCanceled.

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_results is 1 to 50.
  • Optional fields on each videos item (null when unavailable, with the reason in the response perf_unavailable; filling means 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), impressions and ctr (thumbnail impressions and click-through rate in %, from the YouTube Reporting API channel_reach_basic_a1; only for channels where reports were turned on in the analytics page, summed over up to 7 daily reports, period in reach_window).
  • analytics: choose metrics from views, estimatedMinutesWatched, averageViewDuration, averageViewPercentage, subscribersGained, subscribersLost, likes, comments, shares, viewerPercentage. Choose dimensions from day, video, insightTrafficSourceType, ageGroup, gender, country, deviceType. The date range is 365 days at most, and defaults to the last 28 days.
  • For analytics, start and end are YYYY-MM-DD (the end date is today at the latest), dimensions takes at most 2 values, sort is one of the chosen metric or dimension names (prefix - for descending), and max_results is 1 to 200. The video dimension requires both sort and max_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; 403 scope_missing (reconnect the channel and allow the permission) and youtube_forbidden; 404 channel_not_found and not_found_at_youtube; 409 channel_mismatch and connection_not_active; 429 quota_limit (the daily read limit or the YouTube quota was exceeded); 502 youtube_error, youtube_unavailable, report_too_large, report_url_rejected; 503 not_configured and egress_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}'
  • ips lists only the IPs assigned to you. up is the tunnel state (true connected, false down, null unknown); checked_at is when that state was checked.
  • channels are your live YouTube connections; egress_ip_id null means the default (server) egress. title is the channel name and alias is the label you gave it.
  • The PUT body is exactly {"egress_ip_id": "eg_…"} or {"egress_ip_id": null} (back to default); the response is the one updated channels item. 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 GET with jobs:read. PUT requires egress:write and is not accepted with jobs:write (the operator grants the new scopes to older device tokens). Registering, assigning, and deleting static IPs is admin-only.

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:read and social:write scopes (chapter 2). In the examples, $BASE is https://upload.toolulah.com/api/v1 and $TOOLULAH_TOKEN is your token.

9-1. Connected SNS accounts

GET /api/v1/social/connections                        (social:read)
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) or needs_reauth (reconnect on the web). Disconnected accounts are not listed.
  • capabilities: post can publish, insights has permission to read metrics, messages has the inbox permission.
  • Tokens and internal references never appear in any response. Use the id (sc_…) to post.

9-2. Channel groups

GET /api/v1/groups                                    (jobs:read or social:read)
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_id values and use them as channel_id (chapter 8) or SNS targets. A token with only jobs:read sees the YouTube members, and one with only social:read sees the SNS members. Creating, editing, and deleting groups is web-only.

9-3. Post or schedule a video to SNS

POST /api/v1/social/posts                             (social:write)
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)
1 to 128 characters. See idempotency below.
video (required)
The upload_id and sha256 (both required) of a video in the received state. Only MP4 and MOV work (no WebM). Someone else's file or a missing one returns 404 video_upload_not_found; a file that isn't fully received returns 409 video_not_received.
caption (required)
The text. Limits: 2,200 characters for Instagram, Facebook, and TikTok; 500 for Threads. Longer text is rejected, not trimmed.
share_to_feed (optional, default true)
Whether an Instagram reel is also shared to the feed. No effect on other platforms.
not_before (optional)
Post after this time (ISO-8601 with a time zone). Omit it to post right away. Times more than 1 minute in the past, or more than about 14 days ahead, are rejected.
targets (required, 1 to 30)
connection_id (required, no duplicates), not_before (optional, a different time for just this account), and tiktok (TikTok accounts only). An account that isn't yours or is disconnected always gives social.error.target_unavailable, without saying whether it exists.

TikTok options (same rules as the web)

  • privacy_level is required and has no default. It must be one of PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY that 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 (or true) turns it on, and then at least one of brand_organic (your own brand) or brand_content (branded content) must be true. Branded content can't be posted as SELF_ONLY.
  • A video longer than the account's maximum length is rejected.

Response 201 (created) or 200 (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_ref with 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 with 200. Only notation differences (JSON key order, omitted defaults, time zone spelling) still count as the same request. The same client_ref with anything different returns 409 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 with 200. Use a new client_ref to post again. Sending the same video to an account that still has a live post for it, under a different client_ref, returns 409 video_already_scheduled.

If validation fails you get 422 social_invalid with every problem in reasons (see Errors), and nothing is created.

9-4. Post together with a YouTube job (social in POST /jobs)

Add the optional field social to 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 both jobs:write and social:write; otherwise 403 insufficient_scope. Without social (or with null) 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"}]}}'
  • The fields of social are the same as caption, share_to_feed, and targets in 9-3. If you leave caption empty, the text is title + blank line + description.
  • Post start time and deadline follow the YouTube job; give an account its own not_before to change just that account.
  • The YouTube job and the SNS posts are created together or fail together. Manifest errors are reported first, and if SNS validation fails you get 422 social_invalid and no job is created.
  • The response is the usual job body plus a "social_posts" array (the post shape from 9-3). Resending the same client_ref (200) returns the posts that already exist, and adds "social_ignored": true to show that this request's social was not looked at (different content is ignored, not a 409 — send a new client_ref to change it). The field is absent on the first creation.
  • Canceling the YouTube job (chapter 7) also cancels the batch's SNS posts that haven't started sending.

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}
  • Newest first. limit is 1 to 200 (default 50). For the next page pass the response's next_after as after (null means the end). Filter by state and by job_id (the batch from 9-4). An unknown state returns 400 state_invalid; a bad after returns 400 invalid_request.
  • Other people's posts never appear in the list, and asking for one by id returns 404 not_found.
  • permalink is present only when it is an https address. error_code is the reason code when the state is failed, deferred, or unknown.
  • performance exists only for posted posts. Its state is ok (numbers such as views and likes in metrics), pending (not read yet), need_scope (the account hasn't granted metrics permission — reconnect on the web), or error. Metric names differ by platform.
stateMeaning
queuedWaiting. Sent when not_before arrives. It can be canceled only in this state (and deferred).
deferredPostponed (temporary error or limit). Retried at next_attempt_at. Can be canceled.
sending · processingBeing sent to the platform / being processed by the platform.
postedPublished. permalink may be filled in.
failedFailed (see error_code). It isn't sent again automatically; create a new one.
unknownSent, but the result couldn't be confirmed. It isn't re-sent automatically, to avoid a duplicate post. Check the account.
expiredCould not be sent by deadline.
canceledCanceled.

9-6. Cancel a post

POST /api/v1/social/posts/{post_id}/cancel            (social:write)
curl -s -X POST "$BASE/social/posts/sp_0123456789abcdef01234567/cancel" -H "Authorization: Bearer $TOOLULAH_TOKEN"

Only a post that hasn't started sending (queued or deferred) is canceled, and the updated post is returned. Any other state returns 409 post_not_cancelable; someone else's post returns 404.

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.

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 returns 409 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 give cards.error.TEXT_ONLY_PLATFORM) and body is required (no photos and no body gives cards.error.NO_IMAGES). Photo upload_ids in the order to show them. Only your own, received, JPEG photos work (otherwise cards.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, and commercial; passing allow_duet or allow_stitch is rejected with api.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 as upload), sns (video post), card (photo post). For SNS rows, id is the post id (sp_…).
  • at is when the thing happens. from (inclusive) and to (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 returns 400 invalid_request, and omitting to means 90 days from from (or from now). limit is 1 to 500 (default 200); if there are more, "truncated": true is returned, so narrow the window and call again. The to in the response is the end time actually applied. A bad value returns 400 invalid_request.
  • When cancelable is true, cancel a YouTube row with POST /jobs/{job_id}/cancel and an SNS or card row with POST /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 only jobs:read you 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"}
  1. Show the user the user_code and the verification_uri. The user signs in, enters the code, and clicks “Approve”.
  2. 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 returns slow_down, a denial returns access_denied, and after 10 minutes you get expired_token.
  3. Once approved, you get {"access_token": "ust_…", "scopes": [...], "expires_at": "…", "username": "…"} exactly once. It's valid for 90 days, and its scopes are uploads:write jobs:read jobs:write analytics:read social:read social:write egress:read egress:write, plus jobs:publish when 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).
  4. 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, and POST /jobs with social) 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 429 with a Retry-After header (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: targets is 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 twice
  • social.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_required and api.social.caption_invalid · api.social.share_to_feed_invalid
  • api.social.tiktok_invalid: the TikTok options have the wrong shape · api.social.tiktok_not_allowed: tiktok given for a non-TikTok account · api.social.tiktok_photo_option: duet or stitch given for a photo post · api.cards.images_invalid and api.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
HTTPCommon codes
400invalid_request (including bad queries, cursors, and JSON), manifest_invalid, bad_content_range, length_mismatch, sha256_required, invalid_sha256, state_invalid
401unauthorized
403insufficient_scope, consent_required (you must accept the updated terms on the web), password_change_required, attestation_not_human
404not_found (missing or someone else's — jobs, posts, cards, and uploads all answer the same), video_upload_not_found, thumbnail_upload_not_found
408timeout (no chunk body for 60 seconds — resend that chunk)
409offset_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 / 415too_large, chunk_too_large / unsupported_type, magic_mismatch
422Manifest 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)
429rate_limited, too_many_active, too_many_failures
500 / 507disk_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.