API v2 — 4-Step Pipeline

Broadcast Upload API v2

Full control over your video publishing pipeline. Upload first, then decide where and when to publish. Built for teams who need per-platform scheduling, status tracking, and automatic retries.

Open Swagger UI Manage API Token API v1 Docs

4-Step Pipeline

1POST /videos — Upload video
2PATCH /videos/{id} — Update plan (optional)
3POST /videos/{id}/publish — Start publishing
4GET /videos/{id}/publishing-status — Poll status

Decoupled

Upload once, publish whenever you are ready. Change title, description, or platforms after uploading — before publishing.

Retries

Each platform target retries automatically up to 3 times on failure. Check per-platform status and error codes anytime.

Typed Errors

Every error response contains a machine-readable code field so your scripts can branch on specific failure types.

You are not signed in. Examples below use a placeholder token. Sign in to see your real API token in all examples.

Pipeline Overview

How the 4-step workflow fits together

Unlike v1 (which publishes on upload), v2 treats the video asset and the publish action as separate concepts. This lets you review, edit, or queue releases in advance.

POST/api/broadcast/v2/videos

Create video asset

Upload the video file and declare where it will be published. Returns a video_id you use in all subsequent calls.

PATCH/api/broadcast/v2/videos/{video_id}

Update publish plan (optional)

Change the title, description, or platforms before publishing starts. You can also reschedule per-platform release dates.

POST/api/broadcast/v2/videos/{video_id}/publish

Start publishing

Kick off the async publishing pipeline. All draft targets are queued. Returns HTTP 202 Accepted.

GET/api/broadcast/v2/videos/{video_id}/publishing-status

Check per-platform status

Poll this endpoint to see the status of each platform target: pending, in_progress, success, or failed.

Step 1

Create a video asset

Send a multipart/form-data POST with two fields: the video file and a JSON metadata string. The API stores the file and creates platform targets in draft status.

metadata JSON fields

{
  "filename":    "my-video.mp4",          // optional — falls back to the uploaded file name
  "title":       "My Awesome Video",      // optional — falls back to filename
  "description": "Check out this video!", // optional
  "targets": [
    { "platform": "youtube" },
    { "platform": "tiktok",     "release_date": "2026-06-15T09:00:00Z" },
    { "platform": "instagram",  "release_date": "2026-06-15T12:00:00Z" }
  ]
}

Field	Required	Description
`filename`	optional	Override the stored filename. Defaults to the uploaded file's name. Must be unique per account.
`title`	optional	Display title for the post. Defaults to the filename.
`description`	optional	Post description or caption.
`targets`	required	Array of publish targets. Each target needs a `platform` (`youtube`, `tiktok`, `instagram`) and an optional `release_date` (ISO 8601).

Example

curl -X POST https://vbroadcaster.app/api/broadcast/v2/videos \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -F "file=@/path/to/my-video.mp4" \
  -F 'metadata={"filename":"my-video.mp4","title":"My Awesome Video","description":"Check out this video!","targets":[{"platform":"youtube"},{"platform":"tiktok"}]}'

Response (HTTP 201)

{
  "video": {
    "video_id": "vid_a1b2c3d4e5f6g7h8i9j0k1l2",
    "filename": "my-video.mp4",
    "title": "My Awesome Video",
    "description": "Check out this video!",
    "status": "draft",
    "quota": { "used": 1, "limit": 50, "remaining": 49 }
  },
  "targets": [
    { "platform": "youtube", "status": "draft", "release_date": null },
    { "platform": "tiktok",  "status": "draft", "release_date": null }
  ]
}

Save the video_id. You will use it in all subsequent requests (update, publish, status check).

Step 2 — Optional

Update the publish plan

Before publishing starts, you can change the title, description, and platform targets using a PATCH request. Sending a new targets array replaces all existing draft targets.

Important: You cannot update targets that have already been published (status: success). The PATCH returns 409 Conflict if any target has a published result.

Example — change title and add a scheduled Instagram target

curl -X PATCH https://vbroadcaster.app/api/broadcast/v2/videos/vid_a1b2c3d4e5f6g7h8i9j0k1l2 \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "description": "Updated description.",
    "targets": [
      { "platform": "youtube", "release_date": "2026-06-01T10:00:00Z" },
      { "platform": "instagram" }
    ]
  }'

Step 3

Start publishing

POST to /publish to queue all draft targets for publishing. Publishing is asynchronous — the API returns HTTP 202 Accepted immediately and processes platforms in the background.

curl -X POST https://vbroadcaster.app/api/broadcast/v2/videos/vid_a1b2c3d4e5f6g7h8i9j0k1l2/publish \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

Response (HTTP 202)

{
  "video_id": "vid_a1b2c3d4e5f6g7h8i9j0k1l2",
  "publish_request_id": "pubreq_x9y8z7",
  "targets": [
    { "platform": "youtube", "status": "pending", "attempt_count": 0, "max_auto_retries": 3 },
    { "platform": "instagram", "status": "pending", "attempt_count": 0, "max_auto_retries": 3 }
  ]
}

Targets transition from draft → pending → in_progress → success or failed. Failed targets retry up to 3 times automatically.

Step 4

Check publishing status

Poll this endpoint to see the outcome for each platform. The response includes published URLs and error details when available.

curl -X GET "https://vbroadcaster.app/api/broadcast/v2/videos/vid_a1b2c3d4e5f6g7h8i9j0k1l2/publishing-status" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

Example response

{
  "video_id": "vid_a1b2c3d4e5f6g7h8i9j0k1l2",
  "aggregate_status": "success",
  "targets": [
    {
      "platform": "youtube",
      "status": "success",
      "attempt_count": 1,
      "next_retry_at": null,
      "published_url": "https://youtu.be/abc123",
      "remote_post_id": "abc123",
      "last_error": null
    },
    {
      "platform": "instagram",
      "status": "failed",
      "attempt_count": 3,
      "next_retry_at": null,
      "published_url": null,
      "remote_post_id": null,
      "last_error": { "code": "PLATFORM_UPLOAD_FAILED", "message": "Instagram rejected the file format." }
    }
  ]
}

Status values

Status	Meaning
draft	Video uploaded. Publish not started yet.
pending	Target is queued, waiting to be processed.
in_progress	Actively uploading to the platform right now.
success	Published successfully. `published_url` is now set.
failed	All retries exhausted. Check `last_error` for the reason.

Lookup

Find a video by filename

If you know the original filename but not the video_id, use this endpoint to retrieve the full video record including all targets.

curl -X GET "https://vbroadcaster.app/api/broadcast/v2/videos/by-filename?filename=my-video.mp4" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

Error Reference

Machine-readable error codes

All errors return a JSON body with an error.code, error.message, and an optional error.details object with remediation links.

HTTP	Code	When it happens
401	`AUTH_MISSING_BEARER`	Authorization header missing or not using the Bearer scheme.
401	`AUTH_INVALID_TOKEN`	Token is invalid or expired. Regenerate from Settings → API Access.
403	`SUBSCRIPTION_REQUIRED`	No active subscription. Choose a plan to upload.
403	`SUBSCRIPTION_EXPIRED`	Subscription expired. Renew to continue uploading.
403	`SUBSCRIPTION_CANCELLED`	Subscription was cancelled. Choose a new plan.
403	`QUOTA_EXCEEDED`	Video quota for the current plan has been reached.
403	`PLATFORM_NOT_CONNECTED`	One or more platforms are not linked to the account. Go to Settings → Publishing Accounts.
404	`VIDEO_NOT_FOUND`	No video found for the supplied video_id or filename.
409	`VIDEO_ALREADY_EXISTS`	A video with this filename already exists. Use a different filename.
409	`VIDEO_ALREADY_PUBLISHED`	Cannot update targets of a fully published video.
409	`PUBLISH_ALREADY_IN_PROGRESS`	A publish request is already active for this video.
413	`FILE_TOO_LARGE`	File exceeds the 500 MB limit.
415	`UNSUPPORTED_MEDIA_TYPE`	File format is not supported. Use .mp4, .mov, .m4v, or .webm.
422	`INVALID_TARGETS`	targets array is missing or malformed. At least one valid target is required.
422	`INVALID_RELEASE_DATE`	release_date is not a valid ISO 8601 timestamp.
422	`INVALID_METADATA_JSON`	metadata field is missing or not valid JSON.

Comparison

API v1 vs API v2

Feature	v1	v2
Steps to publish	1 (upload + publish in one)	4 (upload → update → publish → status)
Edit before publishing	No	Yes (title, description, platforms)
Per-platform scheduling	One date for all platforms	Different dates per platform
Status polling	Dashboard only	Dedicated status endpoint
Retry on failure	No	Up to 3 automatic retries
Error format	Human-readable string	Machine-readable code + message

Want the interactive Swagger playground?

Try every endpoint directly in your browser with the built-in Swagger UI.

Open Swagger UI →