Skip to main content

Bluesky: profile, status and settings

Read and change the Bluesky account connected to a profile. Every endpoint takes user (the profile username) in the query string or the body.

Changes are merged: anything you do not send stays as it is, and an empty value ("" or []) also leaves the field as it is, so a form that sends every field can change just one. To remove a field, send it as JSON null, send remove_<field>: true, or list it in clear_fields (e.g. "clear_fields": "website,pinned_post", which also works in multipart). If the same record changes in the Bluesky app while we update it, you get 409 bluesky_record_changed instead of overwriting it; retry.

Reads are cached for up to a minute (any change you make through these endpoints refreshes it) and limited to 120 per 5 minutes per Upload-Post account (429 bluesky_read_limit).

Profile​

GET  /api/uploadposts/bluesky/profile/self?user=my-profile
POST /api/uploadposts/bluesky/profile/self

POST accepts JSON or multipart/form-data (to send image files).

NameTypeDescription
display_nameStringUp to 64 characters.
descriptionStringBio, up to 256 characters.
pronounsStringUp to 20 characters.
websiteStringhttp(s) URL.
avatar / bannerFilePNG or JPEG, up to 1,000,000 bytes (multipart).
avatar_url / banner_urlStringPublic http(s) link to a PNG or JPEG instead of a file.
remove_avatar / remove_bannerBooleanRemove the image.
labelsArrayAccount self-labels: !no-unauthenticated (ask apps not to show the account to logged-out visitors), porn, sexual, nudity, graphic-media. Replaces the current set; to change one without touching the rest use labels_add / labels_remove.
labels_add / labels_removeArrayAdd or remove self-labels, keeping the others.
pinned_postStringOne of the account's posts (at:// URI or bsky.app link) to pin. Same as pin.
linksArrayUp to 10 profile links in display order: [{"url": "https://...", "title": "..."}] (https only, title up to 40 characters). The list you send replaces the current one. In multipart, send it as a JSON string.
clear_fieldsArray or StringFields to remove: any of display_name, description, pronouns, website, labels, pinned_post, links, avatar, banner.
curl -X POST https://api.upload-post.com/api/uploadposts/bluesky/profile/self \
-H 'Authorization: Apikey your-api-key-here' \
-F 'user=my-profile' \
-F 'description=We post every weekday' \
-F 'links=[{"url":"https://example.com","title":"Shop"}]' \
-F '[email protected]'
{
"success": true,
"platform": "bluesky",
"action": "update_profile",
"record_uri": "at://did:plc:abc123/app.bsky.actor.profile/self",
"changed": true,
"profile": {
"did": "did:plc:abc123",
"handle": "brand.bsky.social",
"display_name": "Brand",
"description": "We post every weekday",
"pronouns": null,
"website": null,
"avatar_url": "https://cdn.bsky.app/img/avatar/plain/did:plc:abc123/bafkrei...@jpeg",
"banner_url": null,
"labels": [],
"pinned_post": null,
"links": [{"url": "https://example.com", "title": "Shop", "uri": "at://did:plc:abc123/app.bsky.actor.link/3lbq..."}],
"followers_count": 1520,
"follows_count": 87,
"posts_count": 412
}
}

GET answers {"success": true, "platform": "bluesky", "profile": {...}} with the same fields. Image URLs can take a moment to refresh after an update.

Live status​

GET    /api/uploadposts/bluesky/status?user=my-profile
POST /api/uploadposts/bluesky/status
DELETE /api/uploadposts/bluesky/status?user=my-profile

Shows the "live" badge on the account. POST body: status (live, the default and only value Bluesky defines), url (your stream, optional), title and description of the link card (optional), duration_minutes (1 to 10080; the Bluesky app may apply its own maximum). DELETE clears it.

{"success": true, "platform": "bluesky", "action": "set_status", "changed": true,
"status": {"status": "live", "url": "https://twitch.tv/brand", "title": "Live now", "duration_minutes": 90, "created_at": "2026-11-14T10:00:00.000Z"}}

Chat and discovery settings​

GET  /api/uploadposts/bluesky/settings?user=my-profile
POST /api/uploadposts/bluesky/settings

Send any of:

NameValuesWhat it sets
chat_allow_incomingall, following, noneWho can start a direct message with the account.
chat_allow_group_invitesall, following, noneWho can add the account to group chats.
allow_subscriptionsfollowers, mutuals, noneWho can subscribe to notifications of the account's posts.
hide_from_algorithmic_recommendationstrue, falseAsk Bluesky not to recommend the account's content in algorithmic feeds.

The answer always carries the four current values in settings.

Preferences​

GET /api/uploadposts/bluesky/preferences?user=my-profile
PUT /api/uploadposts/bluesky/preferences

The account's private Bluesky app preferences (muted words, saved feeds, content filters, thread view...), as Bluesky returns them, except the account's birth date, which is never returned (neither by GET nor in the answer of PUT; Bluesky keeps it unchanged): a list of objects, each with a $type such as app.bsky.actor.defs#mutedWordsPref.

PUT body: preferences, a list of preference objects to add or replace. Preferences you do not send are always kept. Each object replaces only the matching preference: content filters (contentLabelPref) are matched by label and labelerDid, feed view settings (feedViewPref) by feed, and every other type by its $type.

Some preferences are a whole list in one object (muted words, saved feeds, labelers, hidden posts, interests and app state): sending one replaces the entire list, so it needs "confirm": true. Read the current list with GET first and send it back with your change. To delete, send remove (objects that identify the preference, e.g. {"$type": "app.bsky.actor.defs#contentLabelPref", "label": "gore"}) or remove_types, with "confirm": true. The answer lists what was replaced, added and removed. Birth date and age preferences cannot be changed.

curl -X PUT https://api.upload-post.com/api/uploadposts/bluesky/preferences \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{
"user": "my-profile",
"preferences": [{"$type": "app.bsky.actor.defs#adultContentPref", "enabled": false}]
}'

Moderation labels​

GET /api/uploadposts/bluesky/labels?user=my-profile&post_ids=<at://...>,<at://...>

Labels that Bluesky's moderation (or the labelers in sources, comma-separated DIDs) put on the account and on up to 25 of its posts. Bluesky does not allow wildcard queries, so pass the posts you want to check.

{"success": true, "platform": "bluesky", "cursor": null,
"labels": [{"uri": "at://did:plc:abc123/app.bsky.feed.post/3lbq...", "value": "spam", "source": "did:plc:ar7c4by46qjdydhdevvrndac", "negated": false, "created_at": "2026-11-01T00:00:00Z", "expires_at": null}]}

Error Responses​

  • 400 — nothing_to_change (empty values are ignored), bluesky_text_too_long, invalid_url, invalid_labels, invalid_links, bluesky_image_type, image_download_failed, invalid_status, invalid_duration, invalid_preferences, confirmation_required, bluesky_rejected.
  • 401 — bluesky_reauth_required.
  • 403 — bluesky_not_owner (pinning someone else's post).
  • 409 — bluesky_record_changed.
  • 413 — bluesky_image_too_large (over 1,000,000 bytes).
  • 429 — bluesky_rate_limited, bluesky_read_limit, bluesky_read_rate_limited (too many Bluesky requests for this Upload-Post account right now; wait retry_after seconds). 503 — bluesky_edge_rate_limited, bluesky_guard_unavailable, bluesky_read_capacity (Bluesky is busy for Upload-Post; retry after retry_after), bluesky_login_unavailable (signing in to Bluesky failed for a temporary reason; retry in a minute, no need to reconnect).