Skip to content

Quickstart ​

Publish a video file from a terminal or from your own code, with the socialized.dev CLI, curl or Node.js. Each sample below does the whole job, from the file on your disk to a publication.

Before you start ​

Three things come from the dashboard at dash.socialized.dev:

  1. A connected account. Connecting uses OAuth, so it happens in a browser: connect a YouTube, Instagram or Facebook account on the Connections page. You publish by platform name: each target uses the brand’s connection for that platform.
  2. An API key, made on the Developer page. That page shows the samples below with your own key and brand already in them.
  3. Your brand’s ID (brand_…), on the Developer page too, or from socialized.dev brands list and GET /brands (Brands). With a default brand stored (socialized.dev brands use), the CLI’s --brand-id is optional.

Publish a video ​

Each sample uploads ./clip.mp4 and publishes it to YouTube and Instagram. Put your key in place of sk_your_api_key and your brand’s ID in place of brand_your_brand_id, and list the platforms you connected.

# Uploads ./clip.mp4, then publishes it. Needs curl and jq.
set -euo pipefail
API=https://api.socialized.dev/api/v1
KEY=sk_your_api_key
FILE=./clip.mp4

# Plan the upload: one URL for each part of the file.
PLAN=$(curl -sf "$API/assets" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @- <<JSON
{ "filename": "clip.mp4", "contentType": "video/mp4", "sizeBytes": $(wc -c < "$FILE" | tr -d ' ') }
JSON
)
ASSET=$(jq -r .assetId <<< "$PLAN")
PART_SIZE=$(jq -r .partSize <<< "$PLAN")

# Send each part to its URL, keeping the ETag it answers with.
PARTS=$(jq -r '.parts[] | "\(.partNumber) \(.url)"' <<< "$PLAN" |
  while read -r N URL; do
    ETAG=$(dd if="$FILE" bs="$PART_SIZE" skip=$((N - 1)) count=1 2>/dev/null |
      curl -sf -X PUT --data-binary @- -D - -o /dev/null "$URL" |
      awk 'tolower($1) == "etag:" { print $2 }' | tr -d '\r')
    jq -n --argjson partNumber "$N" --arg etag "$ETAG" '{ partNumber: $partNumber, etag: $etag }'
  done | jq -s .)

# Complete the upload.
curl -sf "$API/assets/$ASSET/complete" -o /dev/null \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @- <<JSON
{ "parts": $PARTS }
JSON

# Publish it. The Idempotency-Key makes a retry safe.
curl -sf "$API/brands/brand_your_brand_id/publications" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @- <<JSON
{
  "videoAssetId": "$ASSET",
  "title": "My first video",
  "targets": [
    { "platform": "youtube" },
    { "platform": "instagram" }
  ]
}
JSON

The CLI’s publications create uploads the file and publishes it in one command. With curl or Node.js you take its four steps yourself:

  1. Plan the upload. POST /assets with the file’s name, type and size answers with the video asset’s assetId, the partSize (10 MiB) and one presigned PUT URL per part.
  2. Send each part to its URL and keep the ETag header it answers with. The URLs are signed for the host header only, so a plain PUT with the bytes and a normal Content-Length is enough (no chunked transfer encoding). A Content-Type on a part is ignored: the asset’s type is the contentType you planned it with.
  3. Complete the upload. POST /assets/{assetId}/complete with each part’s number and ETag, quoted as the header arrives or not, records the asset, ready to publish.
  4. Publish it. POST /brands/{brandId}/publications sends the asset to every target. The Idempotency-Key makes a retry safe (Idempotency).

The publish call answers with the publication and each target, in platform order:

The publish call’s response
{
  "publicationId": "pub_…",
  "status": "queued",
  "targets": [
    {
      "id": "tgt_…",
      "platform": "youtube",
      "status": "pending",
      "format": "short",
      "formatChoice": "platform"
    },
    {
      "id": "tgt_…",
      "platform": "instagram",
      "status": "pending",
      "format": "reel",
      "formatChoice": "platform"
    }
  ]
}

A custom cover is an image uploaded the same way, as its own asset (an image contentType, such as image/jpeg); send its assetId as coverAssetId. The CLI takes --cover ./cover.jpg.

Watch it go live ​

Each target travels pending → processing → published, and the publication settles to done, partial or failed. Read the brand’s publications back, or subscribe to a webhook instead of polling:

curl https://api.socialized.dev/api/v1/brands/brand_your_brand_id/publications \
  -H "Authorization: Bearer sk_your_api_key"

The CLI follows one publication until it settles, reading it every 2 seconds:

CLI: follow one publication
socialized.dev publications get --id pub_… --watch

When a target reaches published, its externalUrl is the live post.


That’s the whole loop: upload once, publish everywhere, watch it settle. Next: Authentication for keys and brands, Publishing a video for the full model, or the REST API reference for every endpoint.

The API is the product; the dashboard is its best-known client.