Appearance
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:
POST /assetswithfilename,contentType, andsizeBytes: returns a plan with one presignedPUTURL per part (parts are 10 MiB).PUTeach part directly to its URL; keep eachETag. Part URLs are signed forhostonly, so no extra headers are required — a plainPUTwith a normalContent-Length(no chunked transfer encoding) is enough. AContent-Typeon a part is ignored: the asset’s type is thecontentTypefrom step 1.POST /assets/{assetId}/completewith 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) answers400 UploadRejectedErrorand leaves the upload open, so complete it again with the right list; an upload that doesn’t exist answers404 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:
| Field | Type | Limit / values | Default | Fallback when absent |
|---|---|---|---|---|
title | string | 1–100 chars | — | base title |
description | string | max 5000 chars | — | base description |
tags | string[] | 500 chars total (the joining commas count) | — | none sent |
categoryId | string | — | — | none sent |
defaultLanguage | string | BCP-47 tag, such as en-GB — language of the title and description | — | none sent |
defaultAudioLanguage | string | BCP-47 tag, such as en — language spoken in the video | — | none sent |
privacyStatus | enum | public | unlisted | private | public | — |
madeForKids | boolean | — | false | — |
containsSyntheticMedia | boolean | — | — | none sent |
publishAt | string | ISO 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 |
playlistIds | string[] | 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:
| Error | Meaning |
|---|---|
422 ConnectionScopeMissingError | the connection lacks youtube.force-ssl — reconnect YouTube |
422 CaptionNotFoundError | a caption assetId doesn’t exist in this team |
422 CaptionUnsupportedTypeError | the 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:
| Field | Type | Limit | Fallback when absent |
|---|---|---|---|
caption | string | max 2200 chars | base description, then base title if it is empty |
Facebook options:
| Field | Type | Limit | Fallback when absent |
|---|---|---|---|
title | string | 1–250 chars | base title |
description | string | max 4000 chars | base 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.
| Platform | Format | Rule |
|---|---|---|
| YouTube | short or video | a 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 |
reel | Instagram posts every video as a Reel | |
reel or page_video | auto 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.
| Target | Refused when |
|---|---|
| YouTube | over 15 minutes, on a channel YouTube says can’t upload long videos yet: verify it at youtube.com/verify, then send again |
| under 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 status | Meaning |
|---|---|
pending | accepted, waiting to send |
processing | being sent to the platform |
published | live; externalUrl is the post. warnings lists the steps that didn’t go through (see below) |
failed | it didn’t go out; failure says why (see below) |
removed_remotely | the 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" }
]
}step | What didn’t go through |
|---|---|
caption | a caption track (YouTube) |
playlist | adding the video to a playlist (YouTube) |
cover | setting the chosen cover (YouTube, Facebook) |
unconfirmed | we 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 |
other | another 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
}
}kind | Why | What to do |
|---|---|---|
reconnect | the 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 |
quota | the 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_upload | YouTube refused a video over 15 minutes from a channel that isn’t verified | verify it at youtube.com/verify, then retry |
file | the platform turned down the file itself | the same file fails again: publish a new file |
source_missing | the uploaded file is gone | publish a new file |
busy | the platform kept refusing or timing out through every try | retry in a few minutes |
internal | socialized.dev failed before the video reached the platform | retry |
unknown | the platform refused it for a reason we don’t recognise | read message before retrying |
New kind values may be added, so treat one you don’t recognise as unknown.
The publication aggregates its targets:
| Publication status | Meaning |
|---|---|
queued | accepted, nothing sent yet |
publishing | at least one target is in flight |
done | every target published |
partial | some published, some failed |
failed | every 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.
filternarrows the list:all(the default),in_progress(a destination still queued or publishing) orattention(a failed destination, or a live one with a step that didn’t go through).qkeeps 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 thoseqmatches, 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 astitle,description, orcoverAssetId) 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 afailedtarget. Only failed targets are retryable: any other status returns409 TargetNotRetryableError, and a failure still being recorded returns409 SettlementPendingError(try again shortly). A failed target never has a live post, so a retry can’t post twice. The body is optional; send newoptionsto retry with them, in the shape that platform’stargets[].optionstakes: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 the422s 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’sfailures.retryable), across every page of the view itsfilterandqname, 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 wasretried, and innotRetriedeach one a retry refused when it came to it, with the errorcodeandmessageits 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, witharchivedAtset), and every post already live on a platform stays live. Returns409 PublicationInFlightErrorwhile 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 apublication.target.removed_remotelywebhook. POST /brands/{brandId}/publications/{id}/targets/{targetId}/mark-removedrecords that removal yourself when the check can’t run because the target’s connection isn’t active. It returns409 TargetVerifiableErrorwhile the connection is active, and409 TargetNotRemovableErrorunless the target ispublished. Marking an already-removed_remotelytarget succeeds.