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.
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"
}POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
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.
| Field | Location | Type as shown | Purpose and checks |
|---|---|---|---|
| content | Request body | string | Post text; check against the 300 graphemes limit. |
| platforms | Request body | array of objects | Targets for the post; include the Bluesky target. |
| platforms[].platform | Request body | string | Set to bluesky for a Bluesky target. |
| platforms[].accountId | Request body | string | Connected Bluesky account identifier, for example bs_123 in the example. |
| scheduledFor | Request body | string (ISO 8601) | Future publishing time; interpreted in timezone when provided, otherwise as UTC. |
| timezone | Request body | string | IANA timezone such as Asia/Tokyo; omitted means scheduledFor is treated as UTC. |
| success | 202 response | boolean | Overall scheduling result. |
| status | 202 response | string | scheduled for a queued post. |
| postId | 202 response | string | Identifier for the scheduled post, for example post_xyz789 in the example. |
| scheduledFor | 202 response | string (UTC) | Resolved publishing time in UTC, for example 2026-09-15T00:00:00.000Z. |
| platforms[].success | 202 response | boolean | Per-target success for the Bluesky target. |
Request and response fields preserved from the source contract example; requiredness beyond the example is not asserted.
| Check | Limit or rule | Failure action |
|---|---|---|
| Post length | Up to 300 graphemes | Shorten the text before scheduling. |
| Images per post | Up to four images | Remove extra images or split into separate posts. |
| Image size | 1 MB per image | Compress or replace the image before scheduling. |
| Video and GIF | Not currently supported | Do not queue video or GIF content as a scheduled Bluesky post. |
| Cancellation | Cancel only before publication | Disable cancel and reschedule once the post has published. |
| Timezone omitted | scheduledFor treated as UTC | Add an IANA timezone when the time is local, or convert to UTC explicitly. |
Limits are preserved from the source page prose and FAQs.
| Decision | Use scheduling when | Use immediate posting when |
|---|---|---|
| Publishing time | A future date and time is known in advance | The post should publish as soon as the request succeeds |
| Timezone | The time is local to a specific IANA timezone | No future local time needs to be resolved |
| Calendar | Posts are queued for a week or month in advance | Content is created and published in one step |
| Changes | The time may need to be edited, rescheduled, or cancelled | No queued post needs later management |
| Cross-platform | Every target can share the same scheduledFor and timezone | Targets 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.
{
"success": true,
"status": "scheduled",
"postId": "post_xyz789",
"scheduledFor": "2026-09-15T00:00:00.000Z",
"platforms": [
{
"platform": "bluesky",
"success": true
}
]
}