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).
| Name | Type | Description |
|---|---|---|
display_name | String | Up to 64 characters. |
description | String | Bio, up to 256 characters. |
pronouns | String | Up to 20 characters. |
website | String | http(s) URL. |
avatar / banner | File | PNG or JPEG, up to 1,000,000 bytes (multipart). |
avatar_url / banner_url | String | Public http(s) link to a PNG or JPEG instead of a file. |
remove_avatar / remove_banner | Boolean | Remove the image. |
labels | Array | Account 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_remove | Array | Add or remove self-labels, keeping the others. |
pinned_post | String | One of the account's posts (at:// URI or bsky.app link) to pin. Same as pin. |
links | Array | Up 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_fields | Array or String | Fields 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:
| Name | Values | What it sets |
|---|---|---|
chat_allow_incoming | all, following, none | Who can start a direct message with the account. |
chat_allow_group_invites | all, following, none | Who can add the account to group chats. |
allow_subscriptions | followers, mutuals, none | Who can subscribe to notifications of the account's posts. |
hide_from_algorithmic_recommendations | true, false | Ask 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; waitretry_afterseconds). 503 —bluesky_edge_rate_limited,bluesky_guard_unavailable,bluesky_read_capacity(Bluesky is busy for Upload-Post; retry afterretry_after),bluesky_login_unavailable(signing in to Bluesky failed for a temporary reason; retry in a minute, no need to reconnect).