149 lines
4.1 KiB
Markdown
149 lines
4.1 KiB
Markdown
# 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:**
|
|
|
|
```json
|
|
{ "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`
|
|
|
|
---
|
|
|
|
## Bulk Change (Header modal)
|
|
|
|
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:**
|
|
|
|
```json
|
|
{
|
|
"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:**
|
|
|
|
```json
|
|
{
|
|
"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`.
|
|
|
|
**Response:** Created `BulkJob`
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- Bulk sync jobs consume YouTube API quota (50 units per video pushed). Check remaining quota via `GET /quota/today` before triggering large bulk pushes. See [[10 - Quota API]].
|
|
- `BulkJob` items record `before` and `after` snapshots for each video, enabling rollback.
|
|
- Rollback is only available for completed jobs and reverses the stored `before` snapshot.
|