devil/youtube-studio-flow

Fork 0

Files

T

devil d5af006443 Initial commit: YouTube Studio Flow (backend, frontend, infrastructure, docs)

2026-08-11 12:27:44 +02:00

4.1 KiB

Raw Blame History

Bulk Jobs API

Base path: /api/v1/bulk-jobs

All endpoints require Authorization: Bearer <jwt>.

Related: 02 - Videos API, 08 - Saved Views API, 10 - Quota API

GET /bulk-jobs

List bulk jobs for the current team.

Query parameters:

Param	Type	Description
`status`	string	Optional filter by job status

Response: BulkJob[]

GET /bulk-jobs/:id

Get a single bulk job with all of its individual item records.

Response: BulkJob with items: BulkJobItem[]

POST /bulk-jobs/:id/rollback

Roll back a completed bulk job, reverting the changes made to each item. Requires EDITOR role.

Response: Updated BulkJob

What rollback does:

For each BulkJobItem with status: "done", the rollback service writes item.beforeSnapshot back to the Video row. beforeSnapshot contains the youtubeSnapshot fields captured before the push: title, tags, categoryId, privacyStatus, defaultLanguage, defaultAudioLanguage, selfDeclaredMadeForKids, embeddable, license, recordingDate.

For SYNC_PUSH jobs specifically:

Rollback is a local-only operation. YouTube is not contacted and the data already pushed to YouTube is not reversed. After rollback:

The Video row's fields are restored to their pre-push values.
lastSyncedHash is not restored — it retains the hash computed at push time.
Because the local fields no longer match lastSyncedHash, the video will show as "push pending" again. This is the expected outcome: the local DB now diverges from YouTube, and a new push is required to re-align them.

This means rollback on a SYNC_PUSH job does not undo anything on YouTube — it only rewinds the local record and marks the video as needing another sync.

GET /bulk-jobs/push-pending/preview

Preview all push-pending videos with field-level diffs showing what will change when pushed to YouTube.

Query parameters:

Param	Type	Description
`sort`	string	Field to sort by
`order`	`asc\|desc`	Sort direction

Response: Array of per-video diff previews

POST /bulk-jobs/push-pending

Create a bulk sync job for a selected set of push-pending videos. Enqueues YouTube sync jobs for each video. Requires EDITOR role.

Request body:

{ "videoIds": ["cuid", "cuid"] }

Tip: use POST /saved-views/:id/execute to get a videoIds list from a saved view. See 08 - Saved Views API.

Response: Created BulkJob

The following endpoints power the bulk metadata change modal in the application header.

POST /bulk-jobs/preview

Preview the effect of a bulk metadata change before applying it.

Request body:

{
  "type": "SET_PRIVACY|SET_TEMPLATE|ADD_TAGS|REMOVE_TAGS|SEARCH_REPLACE_TITLE",
  "payload": {},
  "savedViewId": "cuid"
}

type values:

Type	Description
`SET_PRIVACY`	Change privacy status for matched videos
`SET_TEMPLATE`	Apply a template to matched videos
`ADD_TAGS`	Add tags to matched videos
`REMOVE_TAGS`	Remove tags from matched videos
`SEARCH_REPLACE_TITLE`	Find and replace in video titles

savedViewId is optional. When provided, the operation is scoped to videos matching that saved view.

Response:

{
  "count": 5,
  "type": "SET_PRIVACY",
  "previews": [
    {
      "videoId": "cuid",
      "before": { "privacyStatus": "PRIVATE" },
      "after": { "privacyStatus": "PUBLIC" }
    }
  ]
}

POST /bulk-jobs/apply

Apply a previewed bulk metadata change. Creates a BulkJob record and processes each matched video. Requires EDITOR role.

Request body: Same shape as POST /bulk-jobs/preview.