A social media API for developers: build the draft path first

Use Postbean's verified REST endpoints for accounts, drafts, uploads and publishing, with explicit state and workspace boundaries.

Published api, developers, automation
Illustration: A social media API for developers: build the draft path first

Start your social publishing integration by creating a draft you can read back. A request that sends content immediately is a poor first test of account selection, payload mapping, and credential handling.

Postbean offers a REST API alongside its MCP server. The API can read connected social accounts, store posts, upload media, schedule content, and request publication. You authenticate with a workspace API key and use the same underlying publishing service as the application.

This guide focuses on a small implementation you can inspect: discover an account, save a draft, retain its ID, and check its stored data. Expand into scheduled sends once those boundaries are clear.

Establish access and workspace ownership

Open Settings → Developers and review the access requirements shown for your account before creating a key. Select the project and the permissions this integration needs; keep the token in a server-side secret store or environment.

Send it as Authorization: Bearer <token>. Use Accept: application/json so failures are handled as API responses. For JSON request bodies, send Content-Type: application/json as well.

Bind each integration credential to its intended workspace. If you serve several clients, maintain a server-side mapping from your client identifier to the correct key. Do not let a browser supply an arbitrary token or substitute a workspace header for that mapping.

Log the operation and returned object ID, but exclude the authorization header. A support log should help you find a failed draft without becoming another place where the credential lives.

Read accounts before accepting a target ID

The account listing route is:

GET https://postbean.app/api/social-accounts
Authorization: Bearer <token>
Accept: application/json

It requires accounts:read. Use returned account IDs when building the target list. An account ID is not a username, and a public post ID is not an account ID. Keep those types separate in your application.

Have an operator confirm the username and platform during setup. Store the selected relationship so a later workflow does not choose “the first LinkedIn account” from a list that may have changed.

Social account connection belongs in the panel. Do not build your integration around handing platform passwords to a publishing request. The API operates on the accounts that have already been connected to the workspace.

Create an explicit draft

This example assumes 42 is an account ID returned for your workspace. Replace it with your actual selection:

POST https://postbean.app/api/posts
Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json

{
  "caption": "Our December workshop dates are now available.",
  "post_type": "text",
  "draft": true,
  "social_account_ids": [42]
}

The route uses drafts:write, while the acting user must also be authorized to create the post. Use a text-capable destination for this example. Networks that require media need a different payload.

The draft flag is intentional. In the create flow, omitting both a draft flag and a schedule can queue immediate publication. Never rely on the caption’s wording or a workflow label such as “review” to select a safe state.

Retain the returned public post ID, which is a ULID. Read the stored object with GET /api/posts/{post}. The REST response is a resource representation; inspect its structure when mapping fields into your application rather than assuming it matches a chat tool’s formatted result.

Keep one object through revisions

Edit an existing post through PATCH /api/posts/{post}. Do not create another object when a user changes a caption. Your local record should continue pointing at the same public ID.

For network-specific copy, use platform_overrides:

{
  "platform_overrides": {
    "threads": {
      "caption": "December workshop dates are available. See the booking page."
    }
  }
}

Only use a network that is actually among the post’s targets. This object changes that network’s version; the shared caption can remain more detailed. Postbean evaluates the effective target text when checking publication readiness.

Watch collection replacement semantics. In particular, media_ids is the complete ordered list you want attached. Sending one new ID does not mean “append this to everything already there.” Read the post first if your interface needs to preserve existing attachments.

Upload media in three phases

For a local file, request an upload location with POST /api/media/upload-url. The JSON includes file_name, mime_type, and size_bytes. Read media_id and upload_url from the response.

Send the file bytes with PUT to that returned URL. It is signed, so do not attach your bearer token to it. Set the content type to match the MIME type declared during reservation. Do not build or guess the signed URL yourself.

Confirm the upload with POST /api/media and a body such as {"media_id":51}. Attach that returned media ID through the post’s media_ids list. Image and video processing can continue in the background, so handle readiness separately from successful transfer.

The limits configured for this workflow are 8 MiB per image and 100 MiB per video, measured as 1,024 × 1,024 bytes per MiB. Validate file sizes before attempting a transfer, but keep the server’s response as the authority when something is refused. A destination network may impose further requirements.

Model scheduling as an authorized send

To schedule through the create request, provide a future scheduled_at and set draft: false. Do this only after the content and target list have passed your own review. When updating an existing draft, use the documented update fields and read its resulting state back.

Postbean interprets a datetime without an offset in the workspace time zone. A datetime carrying an offset or Z denotes that exact instant. Store an explicit zone in your own scheduling interface and show the resolved time before submitting it.

Immediate publication of an existing post uses POST /api/posts/{post}/publish-now, with posts:publish. Cancelling its schedule uses POST /api/posts/{post}/cancel. These are distinct operations; do not simulate “publish now” by choosing a timestamp in the past.

For a single destination, the API also exposes PATCH /api/posts/{post}/targets/{target}/schedule. Use a target ID from the post representation and check that the target belongs to the selected post.

Classify failures before retrying

An invalid caption or missing platform option needs a changed request. Postbean returns publication issues for text limits, and rejected scheduling or publication can return HTTP 422. Capture the message and show it where the editor can fix the content.

A missing scope or authorization failure needs credential or access review. It is not a transient network failure. TikTok also requires account-specific choices; retrieve them from GET /api/social-accounts/{account}/tiktok/creator-info instead of inventing an audience value.

For a timeout after creation, check your own saved operation record and the workspace’s posts before creating another object. Do not assume an idempotency header exists. Maintain duplicate protection in your integration unless an endpoint explicitly documents another mechanism.

Give errors an operation context in your own application. An editor should see which source item failed and whether the failure happened during upload, draft storage, or publication. That information helps them choose a correction without restarting every stage. Preserve useful response messages while redacting credentials and signed upload URLs from shared logs.

Before adding batch processing, deliberately submit the same source item twice in your test environment. Your integration should either reuse its stored Postbean ID or stop the second operation for investigation. Also test a successful draft followed by a failed upload, so recovery can continue from the saved draft rather than creating another one.

Observe the publication after the request

Use GET /api/posts/{post}/status to inspect a post after sending. A queued or scheduled state is not proof that a network accepted it. Inspect account-level outcomes, especially when a post has several destinations.

If one destination fails, the verified route POST /api/posts/{post}/targets/{target}/retry can request a targeted retry with publication permission. Resolve the underlying error before using it. Retrying every account can duplicate successful sends in a poorly designed client.

Keep the first release small: one workspace, a selected account, explicit drafts, and a readable failure path. Then add media and scheduling. The API access guide covers credentials; the automation walkthrough applies the same endpoints to workflow tools.

Sources

Write it once. Publish it everywhere.

Connect your networks and schedule your first post in a few minutes. Free plan, no card.

Create your free account