Skip to content

Bluesky Scheduling API

With the Bluesky Scheduling API, a product, agency workflow, automation, or AI system can place a Bluesky post into a queue for a later publishing moment rather than operating its own queue.

Create a scheduled Bluesky post
POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
{
  "content": "A short example update.",
  "platforms": [
    {
      "platform": "bluesky",
      "accountId": "bs_123"
    }
  ],
  "scheduledFor": "2026-09-15T09:00:00",
  "timezone": "Asia/Tokyo"
}
Illustrative request
Example line 1

POST {{API_BASE_URL}}/v1/posts

Illustrative request
Example line 2

x-access-key: YOUR_API_KEY

Illustrative request
Example line 3

Content-Type: application/json

Send the content, the Bluesky account target, a scheduledFor timestamp, and, where needed, a timezone; keep the returned postId so the entry can later be listed, edited, rescheduled, or cancelled. Scheduling fits situations where the moment is decided ahead of time — a campaign launch, a recurring content calendar, or a post prepared in one timezone for release at a chosen local time elsewhere. Immediate posting fits when the entry should go out as soon as the request succeeds and no future moment needs storing or changing.

Bluesky Scheduling API overview: scheduling without maintaining a publishing queue

Future-dated Bluesky publishing can be added to a product, agency workflow, automation, or AI system without running a separate queue. Each future-dated entry is created with its own scheduledFor value, the returned postId is retained, and scheduled entries are listed when a calendar view is needed. It fits SaaS publishing products, agency queues and AI-assisted automations that schedule Bluesky content through a maintained API. Before sending, confirm the text fits the Bluesky limit, images fit the attachment limit, and accountId refers to the connected Bluesky account intended for publication. Correct content or target problems before creation, so the queue holds only entries ready to publish at the chosen moment.

Create a scheduled Bluesky post with POST {{API_BASE_URL}}/v1/posts

Creation uses a POST request to the posts endpoint carrying content, a platforms array with the Bluesky target, scheduledFor, and timezone. In the platforms entry, platform is bluesky and accountId is the connected account identifier. A successful scheduling response carries status 202 and includes success, status set to scheduled, postId, scheduledFor resolved in UTC, and a platforms array reporting success for the Bluesky target. Use postId as the handle for later management and the returned scheduledFor as the authoritative UTC publishing time, rather than recalculating it locally. Absence of scheduled status or postId means queuing cannot be assumed; inspect the response and fix the request before retrying.

Field map for content, platforms, accountId, scheduledFor, timezone, and postId

The field map below separates request fields from response fields so each value can be validated before sending. In the request, content holds the post text, platforms identifies the Bluesky account, scheduledFor holds the future publishing time, and timezone holds the IANA timezone used to interpret that local time. In the response, postId identifies the queued post, scheduledFor is returned in UTC, and platforms reports per-target success. A frequent mistake is confusing the local scheduledFor sent with the UTC scheduledFor returned; store and display the returned UTC value for calendar and queue views, and retain the original timezone alongside it if the interface must show local time.

Timezone handling: IANA timezone, UTC default, and the Asia/Tokyo example

Timezone handling is where a post most easily publishes at the wrong hour. When the time is expressed in local time, pass an IANA timezone such as Asia/Tokyo alongside scheduledFor. The API resolves that local time and returns the corresponding UTC publishing time. Without timezone, scheduledFor is treated as UTC, so 09:00 means 09:00 UTC rather than 09:00 in the user's timezone. In the worked example, 2026-09-15T09:00:00 with timezone Asia/Tokyo resolves to 2026-09-15T00:00:00.000Z in the response. Before queueing a batch, test one post using the same timezone and offset pattern planned for production, then compare the returned UTC time against the intended local time.

Content and media limits: text, up to four images, alt text, and language tags

Text-only posts and posts with supported image attachments can be scheduled, up to four images per post. Bluesky posts support up to 300 graphemes, and each image is limited to 1 MB. Video and GIF posts are not currently supported, so those formats should not be queued in expectation of conversion. Alt text for each image and BCP-47 language tags can be provided through Bluesky-specific settings; if languages are omitted, the default is English. Apply these checks before creation: reject text over 300 graphemes, reject a fifth image, reject any image over 1 MB, and reject video or GIF content. Add alt text whenever an image conveys information the text alone does not.

Managing queued posts: list for a calendar view, edit, reschedule, and cancel before publication

A content calendar is assembled by creating each post with its own scheduledFor value, then listing scheduled posts to render a week or month view. Queued posts can be edited, moved to a different publishing time with the reschedule operation, or cancelled before publication without recreating the content. Cancellation is only available before publication, so cancel and reschedule actions should be disabled once a post has published. When a time changes, confirm the new local time and timezone together, then verify the updated UTC time returned for the queued post. If a post disappears from the scheduled list, check whether it published, was cancelled, or was moved before assuming it was lost.

Cross-platform queuing with a shared scheduledFor and timezone

Compatible content can be scheduled for Bluesky and other supported platforms in one request, with every target sharing the same scheduledFor and timezone. That shared time is a constraint, not a per-platform schedule: audiences needing different local publishing times require separate scheduled posts with their own scheduledFor and timezone values. Before using cross-platform queuing, check that the content format is supported by every target, because a format that works for Bluesky may not work elsewhere. After sending, check the per-platform success entries in the response so a failure on one target is not hidden by success on another.

Account connection with an App Password, handle or DID, and integration ID

Linking a Bluesky account does not use an OAuth redirect flow; instead, the account handle or DID is supplied together with a Bluesky-generated App Password during connection. After connection, use the returned integration ID when scheduling, as described in the account FAQ. Keep the App Password out of logs and out of the scheduling request itself; it belongs to the connection step, while accountId belongs to the post creation request. If scheduling fails for an account target, first confirm the account is connected and the identifier sent matches the connected account, then confirm scheduledFor describes the intended future-dated time and timezone is a valid IANA timezone.

Request and response field map
FieldLocationType as shownPurpose and checks
contentRequest bodystringPost text; check against the 300 graphemes limit.
platformsRequest bodyarray of objectsTargets for the post; include the Bluesky target.
platforms[].platformRequest bodystringSet to bluesky for a Bluesky target.
platforms[].accountIdRequest bodystringConnected Bluesky account identifier, for example bs_123 in the example.
scheduledForRequest bodystring (ISO 8601)Future publishing time; interpreted in timezone when provided, otherwise as UTC.
timezoneRequest bodystringIANA timezone such as Asia/Tokyo; omitted means scheduledFor is treated as UTC.
success202 responsebooleanOverall scheduling result.
status202 responsestringscheduled for a queued post.
postId202 responsestringIdentifier for the scheduled post, for example post_xyz789 in the example.
scheduledFor202 responsestring (UTC)Resolved publishing time in UTC, for example 2026-09-15T00:00:00.000Z.
platforms[].success202 responsebooleanPer-target success for the Bluesky target.

Request and response fields preserved from the source contract example; requiredness beyond the example is not asserted.

Failure and limits matrix
CheckLimit or ruleFailure action
Post lengthUp to 300 graphemesShorten the text before scheduling.
Images per postUp to four imagesRemove extra images or split into separate posts.
Image size1 MB per imageCompress or replace the image before scheduling.
Video and GIFNot currently supportedDo not queue video or GIF content as a scheduled Bluesky post.
CancellationCancel only before publicationDisable cancel and reschedule once the post has published.
Timezone omittedscheduledFor treated as UTCAdd an IANA timezone when the time is local, or convert to UTC explicitly.

Limits are preserved from the source page prose and FAQs.

Scheduling versus immediate posting
DecisionUse scheduling whenUse immediate posting when
Publishing timeA future date and time is known in advanceThe post should publish as soon as the request succeeds
TimezoneThe time is local to a specific IANA timezoneNo future local time needs to be resolved
CalendarPosts are queued for a week or month in advanceContent is created and published in one step
ChangesThe time may need to be edited, rescheduled, or cancelledNo queued post needs later management
Cross-platformEvery target can share the same scheduledFor and timezoneTargets need different times or formats

Decision criteria derived from the scheduling contract behavior.

Frequently asked questions

How do I schedule a Bluesky post?

POST to /v1/posts, naming the Bluesky target through accountId and supplying scheduledFor in ISO 8601 format. Include an IANA timezone if the moment you mean is expressed in local time.

How does timezone handling work?

Supply an IANA timezone, for example Asia/Tokyo. When timezone is left out, scheduledFor is read as UTC. The response gives back the publishing moment resolved to UTC.

What Bluesky content can I schedule?

Text-only entries and entries carrying images are both schedulable, with a maximum of four images. Video and GIF entries are not supported at present.

What are the Bluesky post limits?

Text may run to 300 graphemes. Images are capped at four per entry, and each individual image may not exceed 1 MB.

How do I connect a Bluesky account?

Connection relies on a Bluesky App Password rather than an OAuth redirect. Provide the handle or DID plus that App Password, then use the integration ID returned from connection when scheduling.

Can I add alt text and language information?

Yes. Image alt text and BCP-47 language tags can be supplied via Bluesky-specific settings. When languages are not supplied, English is the default.

Can I edit, reschedule, or cancel a scheduled Bluesky post?

Yes. A queued entry can be edited, shifted to another publishing moment, or cancelled provided publication has not yet happened.

Who is the Bluesky Scheduling API for?

It suits developers, SaaS teams, agencies, automation builders, and AI products requiring programmatic scheduling of social posts.

202 scheduled response
{
  "success": true,
  "status": "scheduled",
  "postId": "post_xyz789",
  "scheduledFor": "2026-09-15T00:00:00.000Z",
  "platforms": [
    {
      "platform": "bluesky",
      "success": true
    }
  ]
}