161 lines
4.6 KiB
Markdown
161 lines
4.6 KiB
Markdown
# Import / Export API
|
|
|
|
All endpoints require `Authorization: Bearer <jwt>`.
|
|
|
|
Related: [[02 - Videos API]], [[03 - Blocks API]], [[04 - Templates API]], [[05 - Collaborators API]]
|
|
|
|
---
|
|
|
|
## Import
|
|
|
|
Base path: `/api/v1/imports`
|
|
|
|
All import endpoints require `EDITOR` role.
|
|
|
|
---
|
|
|
|
### POST /imports/csv/preview
|
|
|
|
Upload and validate a CSV file before committing. Returns a validation report and an `importJobId` to use in the commit step.
|
|
|
|
**Content-Type:** `multipart/form-data`
|
|
|
|
**Form fields:**
|
|
|
|
| Field | Type | Description |
|
|
|---|---|---|
|
|
| `file` | file | CSV file to import |
|
|
| `mapping` | string (JSON) | Maps CSV column names to video fields |
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"importJobId": "cuid",
|
|
"validRows": 50,
|
|
"errors": [
|
|
{ "row": 3, "field": "privacyStatus", "message": "Invalid enum value" }
|
|
]
|
|
}
|
|
```
|
|
|
|
| Field | Description |
|
|
|---|---|
|
|
| `importJobId` | Token to pass to the commit step. |
|
|
| `validRows` | Count of rows that passed validation. |
|
|
| `errors` | Array of per-row validation failures. Each entry has `row` (1-based), `field`, and `message`. Empty array means all rows are valid. |
|
|
|
|
The full validation detail is also stored in `ImportJob.validationReport` (shape: `{ validCount, errorCount, errors }`). There is no `warnings` array.
|
|
|
|
---
|
|
|
|
### POST /imports/csv/commit
|
|
|
|
Enqueues a BullMQ job to process a previously validated CSV import. Returns immediately — the actual row processing happens asynchronously in the worker.
|
|
|
|
> **Known limitation:** The import processor currently only marks the `ImportJob` as `committed` and writes an audit log entry. It does not create or update any `Video` rows. The validated rows from the preview step are not persisted and are not available to the processor. CSV import is effectively incomplete — see the backlog.
|
|
|
|
**Request body:**
|
|
|
|
```json
|
|
{ "importJobId": "cuid" }
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{ "queued": true, "importJobId": "cuid" }
|
|
```
|
|
|
|
---
|
|
|
|
### POST /imports/json/preview
|
|
|
|
Validate a JSON workspace payload (blocks, templates, variables, collaborators) before committing. Returns an `importJobId` to use in the commit step.
|
|
|
|
> **Note:** The payload is **not stored** during preview. The `importJobId` is a commit-guard token only — it confirms a preview was completed and prevents double-commit. The full payload must be resent on commit.
|
|
|
|
**Request body:** Workspace JSON payload
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"importJobId": "cuid",
|
|
"valid": true
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### POST /imports/json/commit
|
|
|
|
Apply a previously validated JSON workspace import. The full workspace payload must be included again — it was not stored during the preview step.
|
|
|
|
Commit is **synchronous** (no queue). Upserts `collaborators`, `blocks`, and `templates` by `id`. `videos`, `videoConfigs`, and `savedViews` in the payload are silently ignored.
|
|
|
|
**Request body:**
|
|
|
|
```json
|
|
{
|
|
"importJobId": "cuid",
|
|
"payload": { }
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{ "committed": true }
|
|
```
|
|
|
|
---
|
|
|
|
## Export
|
|
|
|
Base path: `/api/v1/exports`
|
|
|
|
---
|
|
|
|
### POST /exports/csv
|
|
|
|
Export video metadata as a CSV file download. There is no `scope` parameter — filtering is controlled by `videoIds` or `savedViewId`.
|
|
|
|
**Request body:**
|
|
|
|
```json
|
|
{
|
|
"videoIds": ["cuid1", "cuid2"],
|
|
"savedViewId": "cuid"
|
|
}
|
|
```
|
|
|
|
| Field | Notes |
|
|
|---|---|
|
|
| `videoIds` | Export only these specific videos. If omitted, falls back to `savedViewId`. |
|
|
| `savedViewId` | If `videoIds` is not provided, loads the saved view's stored `queryJson` and uses it to select which videos to export. |
|
|
|
|
If neither field is provided, all videos in the team are exported.
|
|
|
|
**CSV columns:** `youtube_video_id`, `title`, `tags`, `category_id`, `privacy_status`, `published_at`, `scheduled_at`, `template`, `lint_status`
|
|
|
|
**Response:** `text/csv` file download (`studioflow-export-<timestamp>.csv`)
|
|
|
|
---
|
|
|
|
### POST /exports/json
|
|
|
|
Export the full workspace as a JSON object. No request body, no filtering — exports everything.
|
|
|
|
**Response:** JSON object containing: `version`, `exportedAt`, `videos`, `videoConfigs`, `blocks`, `templates`, `collaborators`, `savedViews`
|
|
|
|
> **Note:** `ExportJob` rows are never written. There is no export history or re-download — each call generates the export fresh. See the backlog.
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- The preview-then-commit pattern for imports allows validation errors to be surfaced and reviewed before any data is written.
|
|
- CSV column mapping must be provided as a JSON string in the `mapping` form field, mapping CSV header names to the corresponding video model fields accepted by `PATCH /videos/:id`.
|
|
- JSON workspace exports can be re-imported via `POST /imports/json/preview` and `POST /imports/json/commit`, enabling workspace migration between teams or environments.
|