Skip to content

Publishing a video ​

The quickstart ran the whole loop in one pass. This page is the model underneath it: assets, publications, targets, and the states they travel.

Connections come first ​

You can only publish to a destination you’ve connected. A connection is a platform account you’ve authorized socialized.dev to publish to: a YouTube channel, an Instagram account, a Facebook page. A brand holds at most one connection per platform.

Connecting uses OAuth, so it happens in a browser, which is a dashboard step. Connection management, including listing active connections or removing them, is done only in the dashboard: API keys can’t reach it.

Assets: upload once ​

The source video is an asset, stored once. Assets are team-scoped, meaning a video uploaded once can be published under any brand in the team.

NOTE

If you are using the socialized.dev CLI (socialized.dev publications create), the CLI automatically handles the multipart asset upload ceremony internally for local file paths, making it a single step.

For direct API integrations, uploads are presigned and multipart: you upload each part directly to a URL the API returns:

  1. POST /assets with filename, contentType, and sizeBytes: returns a plan with one presigned PUT URL per part (parts are 10 MiB).
  2. PUT each part directly to its URL; keep each ETag. Part URLs are signed for host only, so no extra headers are required — a plain PUT with a normal Content-Length (no chunked transfer encoding) is enough. A Content-Type on a part is ignored: the asset’s type is the contentType from step 1.
  3. POST /assets/{assetId}/complete with the { partNumber, etag }[] (ETags may be quoted or unquoted). The asset is recorded, ready to publish. A part list storage refuses (a missing part, a wrong ETag, a part under 5 MiB but the last) answers 400 UploadRejectedError and leaves the upload open, so complete it again with the right list; an upload that doesn’t exist answers 404 UploadNotFoundError.

A cover is uploaded as its own image asset (POST /assets with an image contentType) and referenced by the publication as its coverAssetId. For YouTube use a JPEG or PNG under 50 MB — its thumbnail API accepts nothing else. A YouTube target with an over-50MB cover fails validation at publish time rather than posting without its thumbnail; a cover YouTube rejects for another reason (a WebP, or a channel not verified for custom thumbnails) lands as a target warning (a cover step).

A YouTube caption file is uploaded the same way, as its own asset: SubRip (.srt, contentTypeapplication/x-subrip) or WebVTT (.vtt, text/vtt). A YouTube target references it from captions (see Captions and playlists).

An asset exists only once its upload completed: there is no half-uploaded state to publish by accident.

Upload, then publish within 48 hours. An asset that isn’t attached to a publication — as the video, the cover, or a YouTube caption file — within 48 hours of upload is reclaimed automatically: both the stored file and its record are deleted. The clock runs from when you upload, not from last use, so finish the publish inside that window. Once an asset is attached to a publication it persists.

Publications & targets ​

A publication is one “post once”: a title, a description, an optional cover, and a list of targets. Each target is one destination.

curl: publish to two platforms
curl -s -X POST "$API/brands/$BRAND/publications" \
  -H "Authorization: Bearer $SK" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "videoAssetId": "asset_video_…",
    "coverAssetId": "asset_cover_…",
    "title": "Launch clip",
    "description": "…",
    "targets": [
      { "platform": "youtube" },
      { "platform": "instagram" }
    ]
  }'

Each target carries a per-platform options object (it defaults to {}). Up to 10 targets per call. An override wins over the publication’s base title / description; an absent field falls back to the base.

YouTube options:

FieldTypeLimit / valuesDefaultFallback when absent
titlestring1–100 chars—base title
descriptionstringmax 5000 chars—base description
tagsstring[]500 chars total (the joining commas count)—none sent
categoryIdstring——none sent
defaultLanguagestringBCP-47 tag, such as en-GB — language of the title and description—none sent
defaultAudioLanguagestringBCP-47 tag, such as en — language spoken in the video—none sent
privacyStatusenumpublic | unlisted | privatepublic—
madeForKidsboolean—false—
containsSyntheticMediaboolean——none sent
publishAtstringISO 8601 date-time with offset, in the future—publishes immediately
captions{ assetId, language, name? }[]1–10; language a BCP-47 tag; name max 150 chars; each language + name once—none added
playlistIdsstring[]1–10 existing playlist ids of the channel, unique—none added

containsSyntheticMedia is YouTube’s altered or synthetic content disclosure. Set it to true when the video shows realistic content that is altered or generated, such as a real person saying something they didn’t, or a made-up event that looks real. Omit it to send no declaration.

Scheduling a YouTube release ​

Set publishAt to schedule a YouTube video. socialized.dev uploads it right away as private, and YouTube makes it public at publishAt. So the video has finished processing by release time, and any upload problem shows up days early instead of at release. The target turns published once the upload lands; externalUrl works for you straight away and for viewers from publishAt. A scheduled video always ends up public, so publishAt with privacyStatus unlisted or private is a 400, and a time that has already passed is a 422 PublishAtInPastError. Instagram and Facebook have no scheduling: their targets publish immediately.

Captions and playlists (YouTube) ​

captions attaches caption tracks (one per language + name; name is the label viewers see next to the language, and an omitted name sends an empty one). playlistIds adds the video to existing playlists of the connected channel. Both run once the video exists on YouTube.

They need an extra Google permission (youtube.force-ssl). A YouTube connection without it can’t add them: reconnect YouTube on the Connections page first. The API checks up front, before anything uploads:

ErrorMeaning
422 ConnectionScopeMissingErrorthe connection lacks youtube.force-ssl — reconnect YouTube
422 CaptionNotFoundErrora caption assetId doesn’t exist in this team
422 CaptionUnsupportedTypeErrorthe asset isn’t an .srt / .vtt caption file

Once the video is up, a caption or playlist that can’t be added (a playlist that doesn’t exist, a caption file YouTube can’t parse, spent daily quota) doesn’t fail the target: the video is live. The target turns published and lists what didn’t land in its warnings (a caption or playlist step). Each caption costs 400 units of YouTube’s daily API quota and each playlist add about 50.

Instagram options:

FieldTypeLimitFallback when absent
captionstringmax 2200 charsbase description, then base title if it is empty

Facebook options:

FieldTypeLimitFallback when absent
titlestring1–250 charsbase title
descriptionstringmax 4000 charsbase description, then base title if it is empty
format'auto' | 'reel' | 'video'—'auto'

Reels or Page videos. Facebook has two publish surfaces: Reels (/{page-id}/video_reels, 3 seconds to 3 minutes) and Page videos (/{page-id}/videos, much longer clips; the authoritative per-Page limit is GET /{page-id}?fields=video_upload_limits). With format: 'auto' (the default) socialized.dev picks by the same rule YouTube uses for Shorts (see Shape and length). Name reel to post a Reel whatever the shape: a landscape Reel shows with bars. Name video for a Page video. v1’s Page video path is hosted-URL only (file_url); there is no byte-push fallback.

TikTok has no connector yet, so its options stay a free-form bag.

The API validates the effective message (the override, or the base it falls back to) against each platform’s limits. A field that overflows fails the request with a 422 PlatformMessageTooLongError carrying { platform, field, limit } — this catches a base message too long for a platform even when no override is set (for example a 150-character base title fanned out to YouTube’s 100-character cap). YouTube also refuses < and > in a title or description: an effective message holding either fails with a 422 PlatformMessageCharactersError carrying { platform, field, characters }, and a YouTube title or description override holding one is a 400 InvalidRequestError.

The API validates before it accepts: the video and cover must be your team’s assets, a video and an image. You do not specify a connection ID; the server automatically resolves the brand’s single active connection for each platform. If a platform has no active connection, the request fails with a 422 PlatformNotConnectedError. If you specify the same platform twice in one call, the request fails with a 422 DuplicatePlatformError.

Shape and length ​

Every platform turns a video’s shape and length into a format, and socialized.dev reads both from the file when its upload completes (the shape as it plays, after any rotation the file carries). A video is vertical when it is taller than wide or square, and landscape when it is wider than tall.

PlatformFormatRule
YouTubeshort or videoa Short when vertical and 3:00 or less, otherwise a Video. YouTube decides this itself and never reports it, so short is what its rule predicts
InstagramreelInstagram posts every video as a Reel
Facebookreel or page_videoauto picks a Reel when vertical and 3 seconds to 3 minutes long, otherwise a Page video; reel and video post what you name

Every target in the response to a create, and in every read afterwards, carries its format and formatChoice: platform (the platform’s own rule), auto (Facebook’s auto chose it) or requested (your options named it). Both are recorded when the target is created, and again when it is retried, so they say what was sent. A video whose shape or length socialized.dev couldn’t read from the file proves neither a Short nor a Reel, so it is a YouTube video and, under Facebook’s auto, a page_video.

What a platform would refuse is refused before anything is uploaded to it, with 422 VideoNotAcceptedError. Its refusals list every limit the video breaks, on every target at once, in platform order: each names the platform, the rule (min_duration_ms, max_duration_ms or max_size_bytes), the platform’s limit and the video’s figure (actual), in milliseconds or bytes. Drop those targets and send the request again; the others are fine.

TargetRefused when
YouTubeover 15 minutes, on a channel YouTube says can’t upload long videos yet: verify it at youtube.com/verify, then send again
Instagramunder 3 seconds, over 15 minutes, or over 300 MB (it has no other kind of video post)
Facebook with format: 'reel'under 3 seconds or over 3 minutes (auto never picks a Reel it can’t hold)

A figure socialized.dev couldn’t read from the file never refuses: the platform judges it. For YouTube, socialized.dev reads the channel’s long-upload status when it connects and asks YouTube again before a video over 15 minutes, unless YouTube already said yes. If YouTube still rejects a long upload, the target fails with a failure of kind long_upload: verify the channel, then retry the target.

socialized.dev never trims, crops or re-encodes your video.

The lifecycle ​

Once accepted, the publication runs on its own: each target is sent, transient failures are retried, and every target settles to a final state you can read back. Each target travels:

Target statusMeaning
pendingaccepted, waiting to send
processingbeing sent to the platform
publishedlive; externalUrl is the post. warnings lists the steps that didn’t go through (see below)
failedit didn’t go out; failure says why (see below)
removed_remotelythe live post is gone from its platform (see below)

A published target’s warnings are objects, one per step that didn’t go through, in the order they happened. Branch on step; detail is what failed and why, for people and logs:

A published target’s warnings
{
  "warnings": [
    { "step": "cover", "detail": "cover not set: forbidden" },
    { "step": "playlist", "detail": "playlist PL123 not added: playlistNotFound" }
  ]
}
stepWhat didn’t go through
captiona caption track (YouTube)
playlistadding the video to a playlist (YouTube)
coversetting the chosen cover (YouTube, Facebook)
unconfirmedwe couldn’t finish checking on the post after it went live (the connection was lost, or the platform kept failing): the post exists, but its processing (and sometimes its URL) wasn’t confirmed; check it on the platform rather than retrying
otheranother step

New step values may be added as platforms gain steps, so treat one you don’t recognise as other.

A failed target’s failure says why, as far as its fix is concerned, and is null on every other target. Branch on kind; message is what failed, for people and logs, ending with what the platform said in machine terms when it refused the request (Google’s reason; Meta’s code, subcode and type):

A failed target’s failure
{
  "status": "failed",
  "failure": {
    "kind": "quota",
    "message": "youtube init failed: HTTP 403 [code=403 reason=quotaExceeded]",
    "retryAt": 1794124800000
  }
}
kindWhyWhat to do
reconnectthe connection’s access lapsed; isActionNeededOnPlatform is true when the platform wants the account’s owner to act on its own site first (Facebook: a security check or new terms)reconnect the platform in the dashboard, then retry
quotathe platform’s daily upload limit ran out (YouTube’s resets at midnight Pacific time)retry after retryAt (epoch ms); before then it fails the same way
long_uploadYouTube refused a video over 15 minutes from a channel that isn’t verifiedverify it at youtube.com/verify, then retry
filethe platform turned down the file itselfthe same file fails again: publish a new file
source_missingthe uploaded file is gonepublish a new file
busythe platform kept refusing or timing out through every tryretry in a few minutes
internalsocialized.dev failed before the video reached the platformretry
unknownthe platform refused it for a reason we don’t recogniseread message before retrying

New kind values may be added, so treat one you don’t recognise as unknown.

The publication aggregates its targets:

Publication statusMeaning
queuedaccepted, nothing sent yet
publishingat least one target is in flight
doneevery target published
partialsome published, some failed
failedevery target failed

Read it back with GET /brands/{brandId}/publications/{id} (the full record, with every target), or skip polling entirely and subscribe to a webhook.

List publications ​

GET /brands/{brandId}/publications lists the brand’s publications newest first, 50 a page (limit takes up to 100). Each page’s nextCursor goes back as cursor for the next one, and is null on the last. Removed publications aren’t listed.

  • filter narrows the list: all (the default), in_progress (a destination still queued or publishing) or attention (a failed destination, or a live one with a step that didn’t go through).
  • q keeps the publications whose title contains it, ignoring the case of A to Z.
  • counts, on every page, says how many publications each filter lists among those q matches, so a count is never limited to the page you have.
  • failures, on every page, counts the failed destinations of the whole view (failed), the ones a retry can send straight away (retryable) and the publications those belong to.
Terminal: the publications that need attention
curl "https://api.socialized.dev/api/v1/brands/$BRAND_ID/publications?filter=attention" \
  -H "Authorization: Bearer $SOCIALIZED_API_KEY"

Add destinations, retry failures ​

A publication is not frozen once sent:

  • PATCH /brands/{brandId}/publications/{id}: edit the publication details (such as title, description, or coverAssetId) and optionally add new targets. Already-live posts are left untouched.

  • POST /brands/{brandId}/publications/{id}/targets: an append-only endpoint to send the video to more destinations without editing the message. Already-live posts are left untouched.

  • POST /brands/{brandId}/publications/{id}/targets/{targetId}/retry: re-queue a failed target. Only failed targets are retryable: any other status returns 409 TargetNotRetryableError, and a failure still being recorded returns 409 SettlementPendingError (try again shortly). A failed target never has a live post, so a retry can’t post twice. The body is optional; send new options to retry with them, in the shape that platform’s targets[].options takes:

    The retry’s body
    { "options": { "format": "video" } }

    They replace the target’s stored options (an absent field takes its default), so the publication records what was sent. They’re checked as a new destination’s are: a schema failure is 400 InvalidRequestError, and the 422s above (PlatformMessageTooLongError, PlatformMessageCharactersError, VideoNotAcceptedError, PublishAtInPastError, PlatformNotConnectedError, …) apply. Without a body, the target retries with the options it has.

  • POST /brands/{brandId}/publications/retry-failed: retry every failed destination a retry can send straight away (the list’s failures.retryable), across every page of the view its filter and q name, as a bare retry of each would. Destinations waiting on a reconnect, on YouTube verifying the channel or on a daily limit to reset are left alone, as are files a platform turned down. The answer lists what was retried, and in notRetried each one a retry refused when it came to it, with the error code and message its own retry would have answered.

    The body: every retryable failure that needs attention
    { "filter": "attention" }

Writes to a removed publication (see below) return 409 PublicationRemovedError — a removed record is readable but frozen.

Deleting ​

Your records and the live posts are handled separately:

  • DELETE /brands/{brandId}/publications/{id} removes the publication from socialized.dev only: it leaves your list (reads by id keep working, with archivedAt set), and every post already live on a platform stays live. Returns 409 PublicationInFlightError while targets are still publishing.
  • socialized.dev does not delete live posts — delete them on the platform itself. A background check notices a post that has gone and settles its target to removed_remotely (external ids are kept for your records), firing a publication.target.removed_remotely webhook.
  • POST /brands/{brandId}/publications/{id}/targets/{targetId}/mark-removed records that removal yourself when the check can’t run because the target’s connection isn’t active. It returns 409 TargetVerifiableError while the connection is active, and 409 TargetNotRemovableError unless the target is published. Marking an already-removed_remotely target succeeds.

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