Upload a video to Bluesky with the API
Bluesky video goes through a separate video service, not the post call. Here are the four AT Protocol calls with curl, the pitfalls, and the same post as one PostSail request.
The four calls
A Bluesky post does not carry the video file. The file goes to Bluesky's video service first, and the post points to the processed result:
com.atproto.server.getServiceAuthon your PDS: a short-lived token for the video service.app.bsky.video.uploadVideoonvideo.bsky.app: send the file and get a job id.app.bsky.video.getJobStatus: ask until the job isJOB_STATE_COMPLETEDand returns the video's blob.com.atproto.repo.createRecordon your PDS: anapp.bsky.feed.postrecord whoseapp.bsky.embed.videoembed carries the blob.
The commands below use curl and jq, with placeholders in shell variables; no real handle, password or token is shown. Set BSKY_HANDLE and BSKY_APP_PASSWORD yourself.
Before you start: a session
For a script on your own account, an app password from Bluesky's settings is enough. An app that posts for other people should use OAuth instead.
# Sign in with an app password (never the account password)
SESSION=$(curl -s -X POST https://bsky.social/xrpc/com.atproto.server.createSession \
-H "Content-Type: application/json" \
-d "{\"identifier\": \"$BSKY_HANDLE\", \"password\": \"$BSKY_APP_PASSWORD\"}")
ACCESS_JWT=$(echo "$SESSION" | jq -r .accessJwt)
DID=$(echo "$SESSION" | jq -r .did)
# Your PDS: the #atproto_pds service in the DID document
PDS_HOST=$(echo "$SESSION" | jq -r '.didDoc.service[] | select(.id == "#atproto_pds") | .serviceEndpoint' | sed 's|^https://||')1. Get a service token
# 1. A service token for the video service: aud is your PDS, lxm is uploadBlob, 30 minutes
SERVICE_TOKEN=$(curl -s -G "https://$PDS_HOST/xrpc/com.atproto.server.getServiceAuth" \
-H "Authorization: Bearer $ACCESS_JWT" \
--data-urlencode "aud=did:web:$PDS_HOST" \
--data-urlencode "lxm=com.atproto.repo.uploadBlob" \
--data-urlencode "exp=$(( $(date +%s) + 1800 ))" | jq -r .token)audis your own PDS asdid:web:plus its host, not the video service.lxmiscom.atproto.repo.uploadBlob. Bluesky's tutorial recommends a 30-minute expiry, because a long upload can outlive a short token.
2. Upload the file
# 2. Upload the file to Bluesky's video service: you get a job id
JOB_ID=$(curl -s -X POST "https://video.bsky.app/xrpc/app.bsky.video.uploadVideo?did=$DID&name=clip.mp4" \
-H "Authorization: Bearer $SERVICE_TOKEN" \
-H "Content-Type: video/mp4" \
--data-binary @clip.mp4 | jq -r .jobId)Send the raw bytes with the video's Content-Type; curl sets Content-Length from the file. If the same file was uploaded before, the service answers already_exists and points to the earlier job, so keep the job id rather than uploading again.
3. Wait for processing
# 3. Wait until the job is done; the answer then carries the video's blob
while :; do
STATUS=$(curl -s "https://video.bsky.app/xrpc/app.bsky.video.getJobStatus?jobId=$JOB_ID")
STATE=$(echo "$STATUS" | jq -r .jobStatus.state)
[ "$STATE" = "JOB_STATE_COMPLETED" ] && break
[ "$STATE" = "JOB_STATE_FAILED" ] && { echo "$STATUS"; exit 1; }
sleep 2
done
BLOB=$(echo "$STATUS" | jq -c .jobStatus.blob)Processing takes longer than the upload. In our own test on 10 November 2026, a 6-second video was live 20.7 seconds after the request, most of it Bluesky's processing. One run, not a benchmark.
4. Create the post
# 4. Create the post with a video embed (aspectRatio: the video's width and height)
curl -s -X POST "https://$PDS_HOST/xrpc/com.atproto.repo.createRecord" \
-H "Authorization: Bearer $ACCESS_JWT" \
-H "Content-Type: application/json" \
-d "$(jq -n --arg did "$DID" --argjson blob "$BLOB" --arg now "$(date -u +%Y-%m-%dT%H:%M:%S.000Z)" '{
repo: $did, collection: "app.bsky.feed.post",
record: {"$type": "app.bsky.feed.post", text: "New clip", createdAt: $now,
embed: {"$type": "app.bsky.embed.video", video: $blob, aspectRatio: {width: 1080, height: 1920}}}}')"aspectRatiolets apps size a vertical video before it loads; read width and height from the file (for example with ffprobe).- Text is at most 300 characters, counted as graphemes, and 3,000 bytes. Links and #hashtags are clickable only with facets, which mark UTF-8 byte ranges in the text.
- If the answer to
createRecordis lost, sending it again makes a second post. Pass your ownrkey(a TID) in the request: a retry then fails with "already exists" instead of posting twice. PostSail does this for you.
Limits and pitfalls
- Bluesky accepts video up to 3 minutes and 100 MB.
- There is a daily limit on video posts, and accounts hosted by Bluesky need a verified email address before they can upload video.
- Uploading the video as an ordinary blob with
com.atproto.repo.uploadBlobalso works, but Bluesky's tutorial notes that processing then starts only after the post is created. - Bluesky has no drafts: the post is public as soon as
createRecordsucceeds.
The same post with PostSail
Connect the Bluesky account once in the dashboard (Bluesky's own sign-in page; PostSail never sees the password), upload the file and send one request. PostSail checks the video against these limits before anything goes out, makes the four calls, adds facets for links and hashtags, retries temporary errors without posting twice and reports the result. The same request can also post to X: see Post to X and Bluesky with one API request.
# 1. Start the upload: you get id, upload_url, method, headers and expires_at
curl -X POST https://postsail.app/api/v1/uploads \
-H "Authorization: Bearer $POSTSAIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content_type": "video/mp4", "size_bytes": 7340032}'
# 2. Send the file to upload_url (method PUT, the Content-Type from headers)
curl -X PUT "$UPLOAD_URL" -H "Content-Type: video/mp4" --data-binary @clip.mp4
# 3. Create the post; replace UPLOAD_ID with the id from step 1
curl -X POST https://postsail.app/api/v1/posts \
-H "Authorization: Bearer $POSTSAIL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: clip-2026-11-20" \
-d '{"external_id":"clip-2026-11-20","media_upload_id":"UPLOAD_ID","targets":[{"account":"brand-bluesky","text":"New clip"}]}'import {readFile, stat} from "node:fs/promises";
const auth = {Authorization: `Bearer ${process.env.POSTSAIL_API_KEY}`};
const file = "clip.mp4";
// 1. Start the upload
const start = await fetch("https://postsail.app/api/v1/uploads", {
method: "POST",
headers: {...auth, "Content-Type": "application/json"},
body: JSON.stringify({content_type: "video/mp4", size_bytes: (await stat(file)).size}),
}).then((r) => r.json());
// 2. Send the file with the given method and headers
const put = await fetch(start.upload_url, {method: start.method, headers: start.headers, body: await readFile(file)});
if (!put.ok) throw new Error(`upload failed: ${put.status}`);
// 3. Create the post with the upload id
const post = await fetch("https://postsail.app/api/v1/posts", {
method: "POST",
headers: {...auth, "Content-Type": "application/json", "Idempotency-Key": "clip-2026-11-20"},
body: JSON.stringify({external_id: "clip-2026-11-20", media_upload_id: start.id, targets: [{"account":"brand-bluesky","text":"New clip"}]}),
}).then((r) => r.json());
console.log(post.id, post.status);import os
import requests
API = "https://postsail.app/api"
auth = {"Authorization": f"Bearer {os.environ['POSTSAIL_API_KEY']}"}
path = "clip.mp4"
# 1. Start the upload
start = requests.post(f"{API}/v1/uploads", headers=auth,
json={"content_type": "video/mp4", "size_bytes": os.path.getsize(path)}).json()
# 2. Send the file with the given method and headers
with open(path, "rb") as f:
requests.request(start["method"], start["upload_url"], headers=start["headers"], data=f).raise_for_status()
# 3. Create the post with the upload id
post = requests.post(f"{API}/v1/posts", headers={**auth, "Idempotency-Key": "clip-2026-11-20"}, json={
"external_id": "clip-2026-11-20",
"media_upload_id": start["id"],
"targets": [{"account":"brand-bluesky","text":"New clip"}],
}).json()
print(post["id"], post["status"])Text posts, dry runs and results are in How to post to Bluesky through an API.
Sources
- Bluesky's video upload tutorial, docs.bsky.app/docs/tutorials/video, read 17 November 2026: the service token, the video service, job status and the video embed.
- Our own Bluesky integration, public since 10 November 2026: it makes these calls for every Bluesky video posted through PostSail.