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:

  1. com.atproto.server.getServiceAuth on your PDS: a short-lived token for the video service.
  2. app.bsky.video.uploadVideo on video.bsky.app: send the file and get a job id.
  3. app.bsky.video.getJobStatus: ask until the job is JOB_STATE_COMPLETED and returns the video's blob.
  4. com.atproto.repo.createRecord on your PDS: an app.bsky.feed.post record whose app.bsky.embed.video embed 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.

shell · AT Protocol
# 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

shell · AT Protocol
# 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)
  • aud is your own PDS as did:web: plus its host, not the video service.
  • lxm is com.atproto.repo.uploadBlob. Bluesky's tutorial recommends a 30-minute expiry, because a long upload can outlive a short token.

2. Upload the file

shell · AT Protocol
# 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

shell · AT Protocol
# 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

shell · AT Protocol
# 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}}}}')"
  • aspectRatio lets 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 createRecord is lost, sending it again makes a second post. Pass your own rkey (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.uploadBlob also 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 createRecord succeeds.

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.

curl
# 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"}]}'
Node.js
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);
Python
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.