Dashboard Get API key
Getting started

Bugle API

One REST API to connect social accounts and publish to X, Instagram, Facebook, TikTok, YouTube, LinkedIn, Threads, Pinterest and Bluesky. Bugle handles OAuth, token refresh, media and each platform's rules. You send one request.

Everything is plain JSON over HTTPS. There is no SDK to install: any language that can make an HTTP request works. The dashboard uses the same API, so anything you can do there you can do in code.

Getting started

Quickstart

Three requests take you from a fresh API key to a published post.

Get your API key

Sign in to the dashboard and copy your secret key from the API key page. Keys start with sk_.

Connect an account

Ask Bugle for an OAuth link, send your user to it, and they come back connected. Bluesky connects with an app password instead.

Publish

Send the text, optional media and the account IDs to POST /v1/posts. Bugle validates it for every platform before it is queued.

The account ID comes from the connect step or from List accounts. Follow the result in the dashboard, with Get post, or with a webhook.

Getting started

Authentication

Every request to /v1 needs your secret API key. Send it in the x-api-key header, or as a bearer token in Authorization.

A key belongs to one project. Everything you create (profiles, accounts, posts, webhooks) lives inside that project, and other keys cannot see it.

Keep keys on your server. Never ship a key in a mobile app, browser code or a public repository. Anyone with the key can post to every connected account in the project.

A missing or wrong key returns 401 with the code unauthorized.

Either header works
# Recommended
x-api-key: sk_live_xxxxxxxxxxxx

# Also accepted
Authorization: Bearer sk_live_xxxxxxxxxxxx
Getting started

Conventions

  • Base URL: https://api.bugle.pro. All endpoints live under /v1.
  • JSON in, JSON out. Send content-type: application/json with a body. Request bodies can be up to 2 MB; upload files with upload URLs, not in the body.
  • IDs are strings with a prefix that tells you the type: prf_ profile, acc_ account, post_ post, med_ media, wh_ webhook, evt_ event.
  • Times are ISO 8601 strings in UTC, for example 2026-11-05T09:30:00.000Z. When you send one, include an offset.
  • Lists come wrapped in { "data": [...] }. The posts list adds a nextCursor for paging.
  • Deletes return 204 No Content, except cancelling a post, which returns the cancelled post.
Getting started

Errors

Errors use normal HTTP status codes and always have the same body: a stable code to branch on, a human-readable message, and sometimes details. Messages may change, so match on code.

StatusCodeWhen
400bad_requestThe body or query is malformed. details lists each field as { path, message }.
400platform_not_configuredThe platform has no app on this server yet, or needs your own app.
400connect_failedCredentials were rejected, for example a wrong Bluesky app password.
401unauthorizedMissing or invalid API key.
403forbiddenAn upload URL is invalid or has expired.
404not_foundThe resource does not exist in this project.
409conflictThe action does not fit the current state, like rescheduling a published post.
422validation_failedThe post breaks a platform rule. details lists the problems per account.
429rate_limitedToo many requests. See rate limits.
502platform_errorThe social platform returned an error.
500internal_errorSomething went wrong on our side.
{
  "error": {
    "code": "validation_failed",
    "message": "The post does not meet some platforms' rules",
    "details": [
      {
        "accountId": "acc_8Fq2k1Xr",
        "errors": ["x: text is longer than 280 characters"]
      }
    ]
  }
}
Getting started

Rate limits

Each API key can make 300 requests per minute. Past that you get 429 with rate_limited, and the message says how many seconds to wait. Back off and retry.

Social platforms have their own limits too, for example Threads allows 250 posts per account per day. When a platform says "slow down", Bugle retries the post for you. You don't need to handle it.

To follow posts, prefer webhooks over polling: they don't count toward your limit.

Guides

Profiles

A profile is one of your users or clients. Every connected account belongs to a profile, so a social media tool can keep each customer's accounts apart, and an agency can group accounts per client.

You don't have to use profiles. If you never pass a profileId, Bugle creates one default profile and puts every account in it.

Set externalId to the user's ID in your own database to find their profile later without storing Bugle IDs.

Guides

Connecting accounts

Most platforms connect with OAuth: the account owner signs in on the platform's own page and approves your app. You never see their password.

GET /v1/connect/:platform→redirect user to url→user approves→back to redirectUrl
  1. Call Start OAuth with an optional profileId and the redirectUrl of a page in your app.
  2. Send the user to the returned url. It is valid for 10 minutes.
  3. After approval the platform returns to Bugle, Bugle stores the tokens (encrypted) and then redirects to your redirectUrl with the result in the query string.
Query parameterValue
statussuccess or error
platformFor example linkedin
accountIdsComma-separated new account IDs (on success). Facebook can return several Pages at once.
profileIdThe profile the accounts were added to (on success)
errorWhat went wrong (on error)

Without a redirectUrl, Bugle shows a simple "Account connected, you can close this window" page.

Bluesky

Bluesky has no OAuth app review. The user creates an app password in Bluesky (Settings → Privacy and security → App passwords) and you send it to Connect with credentials. Never ask for their main password.

Tokens and reconnecting

Bugle refreshes tokens before they expire. If a platform revokes access (the user removed your app, changed their password, or the token cannot be refreshed), the account's status becomes reauth_required and you get an account.reauthorization_required webhook. Run the connect flow again for the same profile to fix it.

https://yourapp.com/connected
  ?status=success
  &platform=linkedin
  &accountIds=acc_8Fq2k1Xr
  &profileId=prf_Kd81mZ
Guides

Publishing and scheduling

A post is one piece of content sent to one or more accounts. Each account in platforms is a target and has its own status, URL and error, so a post can succeed on LinkedIn and fail on X.

Bugle checks every target against its platform's rules before anything is queued. If one target breaks a rule you get 422 validation_failed and nothing is posted.

Now or later

  • "publishNow": true or no time at all: queued right away.
  • "scheduledFor": "2026-11-05T09:30:00+03:00": published at that moment. Add timezone (an IANA name like Europe/Istanbul) to keep it for your records.
  • Change the time with Reschedule post, or stop it with Cancel post.

Different text per platform

Set content inside a target to override the main text for that account only. Handy for a short X version of a long LinkedIn post.

Statuses

Post statusMeaning
queuedWaiting to be published, usually for a few seconds.
scheduledWill be published at scheduledFor.
publishingBeing sent to the platforms right now.
publishedEvery target succeeded.
partialSome targets succeeded, some failed. Check each target's error.
failedNo target succeeded.
cancelledYou cancelled it before it went out.

Each target is pending, published or failed. Temporary problems (network errors, platform outages, platform rate limits) are retried automatically, up to 3 attempts per target with growing delays. Permanent problems fail at once with the platform's message in error.

Guides

Uploading media

Posts reference media by public URL. If your files are already public (your CDN, S3), put the URLs straight into mediaItems. Otherwise upload them to Bugle in two steps:

  1. Call Create upload URL with the file's MIME type.
  2. PUT the raw file bytes to uploadUrl with the returned headers. The URL works for one hour.
  3. Use publicUrl in your post.

Accepted types: image/jpeg, image/png, image/gif, image/webp, video/mp4, video/quicktime.

Instagram, Threads, Facebook and TikTok photo posts download the file from its URL themselves, so the URL must be reachable from the public internet. localhost URLs will fail.
2 · Upload the file
curl -X PUT "$UPLOAD_URL" \
  -H "content-type: video/mp4" \
  --data-binary @launch.mp4
Guides

Webhooks

Register an HTTPS endpoint and Bugle sends it a POST with a JSON body whenever something happens. Subscribe to all events or only some.

EventSent whendata
post.scheduledA post was created with a future timePost
post.publishedEvery target succeededPost
post.partialSome targets failedPost
post.failedEvery target failedPost
post.cancelledYou cancelled a postPost
account.connectedAn account was connectedAccount
account.reauthorization_requiredThe account must be connected againaccountId, platform, reason
account.disconnectedAn account was disconnectedaccountId, platform
webhook.testYou pressed "Send test"message

Verifying signatures

Each request carries three headers. Check the signature before trusting the body:

  • x-webhook-id: the event ID. The same event can arrive twice; ignore IDs you have seen.
  • x-webhook-timestamp: Unix seconds. Reject old timestamps (for example older than 5 minutes).
  • x-webhook-signature: sha256= followed by the hex HMAC-SHA256 of "<timestamp>.<raw body>", keyed with your endpoint's secret.

The secret (whsec_…) is shown once, when you create the endpoint.

Retries

Answer with any 2xx within 10 seconds. Anything else counts as a failure, and Bugle retries up to 5 times with growing delays. Do slow work after you respond.

{
  "id": "evt_3Lk9qPz",
  "type": "post.published",
  "createdAt": "2026-11-05T06:30:04.211Z",
  "data": {
    "id": "post_Vn2aQ8",
    "status": "published",
    "content": "Dark mode is here 🌙",
    "platforms": [
      {
        "platform": "x",
        "accountId": "acc_X1",
        "status": "published",
        "url": "https://x.com/yourapp/status/1854…"
      }
    ]
  }
}
verify.js (Node.js)
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, headers, secret) {
  const ts = headers['x-webhook-timestamp'];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const mac = createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`).digest('hex');
  const a = Buffer.from(`sha256=${mac}`);
  const b = Buffer.from(headers['x-webhook-signature'] ?? '');
  return a.length === b.length && timingSafeEqual(a, b);
}
Guides

Bring your own app

By default accounts connect through Bugle's own approved apps, so the consent screen says "Bugle". For any OAuth platform you can register your own developer app instead. Then:

  • the consent screen shows your app's name and logo,
  • the platform's rate limits and quotas are yours alone,
  • you keep the platform relationship if you ever leave.

X always needs your own app. X bills API usage per developer account, so each customer posts through their own X app and pays X directly.

To set it up, add Bugle's callback URL (https://api.bugle.pro/v1/connect/<platform>/callback, also returned by List platforms) to your app's settings, then save the client ID and secret with Save your app. New connections use your app from then on. The secret is encrypted and never returned.

Guides

Platform rules

What each platform accepts today. Bugle enforces these before queueing, so a post that passes validation will not be rejected for these reasons later.

PlatformConnectText limitMediaOptions (platforms[].options)
XOAuth, your own app280 (links count as 23)Up to 4 images, or 1 videoreplyToId
InstagramOAuth (Business or Creator account)2,200Required. Up to 20 items as a carousel; videos post as Reelstype: "story" · shareToFeed
Facebook PagesOAuthVery longUp to 10 images, or 1 video on its ownlink
TikTokOAuth2,200Required. 1 video, or up to 35 imagesprivacyLevel (required) · userConsent: true (required) · disableComment · disableDuet · disableStitch · brandContent · brandOrganic · mode: "inbox"
YouTubeOAuthTitle 100, description 5,000Exactly 1 videotitle (else the first line) · privacyStatus · tags · categoryId · madeForKids · short
LinkedInOAuth3,000Up to 9 images (no video yet)visibility: "PUBLIC" or "CONNECTIONS" · link
ThreadsOAuth500Up to 20 items as a carouselNone
PinterestOAuthDescription 800, title 100Exactly 1 image (no video yet)boardId (required) · title · link
BlueskyApp password300Up to 4 images, under 1 MB each (no video yet)None

TikTok's allowed privacyLevel values differ per creator. Read them from the creator-info account resource and let the user choose; TikTok requires that there is no preselected default. Pinterest board IDs come from the boards resource.

API reference

API reference

Every endpoint, with its parameters and a real response.

List platforms

GET/v1/platforms

The platforms this server supports and whether you can connect them right now.

FieldDescription
availablebooleanAccounts can be connected now.
byokRequiredbooleanYou must save your own app first (X).
auth"oauth2" | "credentials"Which connect flow to use.
callbackUrlstringFor OAuth platforms: the URL to add to your own app.
{
  "data": [
    {
      "id": "linkedin",
      "name": "LinkedIn",
      "auth": "oauth2",
      "byokRequired": false,
      "available": true,
      "callbackUrl": "https://api.bugle.pro/v1/connect/linkedin/callback"
    },
    {
      "id": "bluesky",
      "name": "Bluesky",
      "auth": "credentials",
      "byokRequired": false,
      "available": true
    }
  ]
}

Create profile

POST/v1/profiles

Creates a profile for one of your users or clients.

BodyDescription
namerequiredstring, max 200A label you'll recognise.
externalIdstring, max 200The user's ID in your own system.
{
  "id": "prf_Kd81mZ",
  "name": "Acme Coffee",
  "externalId": "user_123",
  "isDefault": false,
  "createdAt": "2026-11-03T14:12:09.481Z"
}

List profiles

GET/v1/profiles

All profiles in the project, oldest first. Get a single one with GET /v1/profiles/:id.

{
  "data": [
    { "id": "prf_Def0", "name": "Default", "externalId": null, "isDefault": true, "createdAt": "2026-11-01T09:00:00.000Z" },
    { "id": "prf_Kd81mZ", "name": "Acme Coffee", "externalId": "user_123", "isDefault": false, "createdAt": "2026-11-03T14:12:09.481Z" }
  ]
}

Delete profile

DELETE/v1/profiles/:id

Deletes an empty profile. If it still has connected accounts you get 409 conflict; disconnect them first.


    

Start OAuth

GET/v1/connect/:platform

Returns the platform's sign-in URL. Send the user there. See Connecting accounts for the whole flow.

QueryDescription
profileIdstringProfile to add the account to. Defaults to the default profile.
redirectUrlURLWhere to send the user afterwards, with the result in the query string.

Returns 400 platform_not_configured if the platform has no app on the server, or needs your own app.

{
  "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=…&state=…",
  "expiresIn": 600
}

Connect with credentials

POST/v1/connect/bluesky

Connects a Bluesky account with an app password. The password is used once to start a session and is not stored.

BodyDescription
identifierrequiredstringHandle (name.bsky.social) or email.
appPasswordrequiredstringAn app password, never the main password.
profileIdstringProfile to add the account to.
serviceURLFor self-hosted servers. Defaults to bsky.social.

A wrong handle or password returns 400 connect_failed.

{
  "data": [
    {
      "id": "acc_Bs7nR2",
      "profileId": "prf_Def0",
      "platform": "bluesky",
      "platformUserId": "did:plc:4kq…",
      "username": "acme.bsky.social",
      "displayName": "Acme Coffee",
      "avatarUrl": "https://cdn.bsky.app/img/avatar/…",
      "status": "active",
      "tokenExpiresAt": null,
      "createdAt": "2026-11-03T14:20:41.002Z"
    }
  ]
}

List accounts

GET/v1/accounts

Connected accounts, oldest first. Disconnected accounts are left out. Get one with GET /v1/accounts/:id. Tokens are never returned.

QueryDescription
profileIdstringOnly this profile's accounts.
platformstringOnly this platform, e.g. instagram.

status is active or reauth_required.

{
  "data": [
    {
      "id": "acc_8Fq2k1Xr",
      "profileId": "prf_Kd81mZ",
      "platform": "linkedin",
      "platformUserId": "u2Hk9…",
      "username": "acme-coffee",
      "displayName": "Acme Coffee",
      "avatarUrl": "https://media.licdn.com/…",
      "status": "active",
      "tokenExpiresAt": "2027-01-02T14:20:41.000Z",
      "createdAt": "2026-11-03T14:20:41.002Z"
    }
  ]
}

Disconnect account

DELETE/v1/accounts/:id

Deletes the stored tokens and hides the account. Scheduled posts that target it will fail. Sends account.disconnected.


    

Account resources

GET/v1/accounts/:id/resources/:name

Reads platform data you need before posting.

NameReturns
boardsPinterestThe user's boards: id, name, privacy.
creator-infoTikTokTikTok's creator info, including privacy_level_options and posting limits.
{
  "data": [
    { "id": "1029384756", "name": "Recipes", "privacy": "PUBLIC" },
    { "id": "1029384757", "name": "Shop", "privacy": "PUBLIC" }
  ]
}

Create upload URL

POST/v1/media/upload

Returns a one-hour URL to PUT a file to, and the public URL to use in posts.

BodyDescription
mimeTyperequiredstringOne of the accepted types.
filenamestring, max 255Original file name, for your records.
{
  "mediaId": "med_7McYQG9Z",
  "uploadUrl": "https://api.bugle.pro/v1/media/local-upload/…?exp=…&sig=…",
  "method": "PUT",
  "headers": { "content-type": "image/jpeg" },
  "publicUrl": "https://api.bugle.pro/media/prj_…/med_7McYQG9Z.jpg",
  "expiresIn": 3600
}

Delete media

DELETE/v1/media/:id

Deletes an uploaded file. Posts already published keep their copy on the platform.


    

Create post

POST/v1/posts

Validates the post for every target, then queues or schedules it. See Publishing and scheduling.

BodyDescription
platformsrequiredarray, 1–50The targets. Each account may appear once.
platforms[].accountIdrequiredstringAn active account in this project.
platforms[].contentstringText for this account only.
platforms[].optionsobjectPlatform options, like a YouTube title.
contentstring, max 10,000The text. Can be empty if there is media.
mediaItemsarray, max 35{ url, type: "image" | "video", altText? }, in order.
publishNowbooleanQueue right away (the default when there is no time).
scheduledForISO 8601 with offsetWhen to publish. Cannot be combined with publishNow.
timezonestringIANA time zone, kept for your records.

Returns the post with status queued or scheduled, or 422 validation_failed.

{
  "id": "post_Vn2aQ8",
  "status": "queued",
  "content": "New autumn menu is live ☕",
  "mediaItems": [
    { "url": "https://cdn.acme.com/menu.jpg", "type": "image", "altText": "Three pumpkin lattes on a table" }
  ],
  "scheduledFor": null,
  "timezone": null,
  "createdAt": "2026-11-03T14:31:10.552Z",
  "publishedAt": null,
  "platforms": [
    { "platform": "instagram", "accountId": "acc_Insta1", "username": "acmecoffee", "status": "pending", "platformPostId": null, "url": null, "error": null, "publishedAt": null },
    { "platform": "pinterest", "accountId": "acc_Pin1", "username": "acmecoffee", "status": "pending", "platformPostId": null, "url": null, "error": null, "publishedAt": null }
  ]
}

List posts

GET/v1/posts

Posts in the project, newest first.

QueryDescription
statusstringOnly posts with this status.
limit1–100, default 20Page size.
beforepost IDPass the previous page's nextCursor to get the next page.

nextCursor is null on the last page.

{
  "data": [ { "id": "post_Vn2aQ8", "status": "failed", "…": "…" } ],
  "nextCursor": null
}

Get post

GET/v1/posts/:id

One post with the live status of every target, including the published URL or the platform's error.

{
  "id": "post_Vn2aQ8",
  "status": "partial",
  "content": "New autumn menu is live ☕",
  "publishedAt": "2026-11-03T14:31:14.918Z",
  "platforms": [
    { "platform": "instagram", "status": "published", "url": "https://www.instagram.com/p/C9x…", "error": null },
    { "platform": "pinterest", "status": "failed", "url": null, "error": "Board not found" }
  ]
}

Reschedule post

PATCH/v1/posts/:id

Moves a scheduled post to a new future time. Other statuses return 409 conflict.

BodyDescription
scheduledForrequiredISO 8601 with offsetThe new time. Must be in the future.
timezonestringIANA time zone.

Cancel post

DELETE/v1/posts/:id

Stops a scheduled or queued post and returns it with status cancelled. Posts that are already publishing or published return 409 conflict; Bugle does not delete posts from the platforms.

Create webhook

POST/v1/webhooks

Registers an endpoint. The response includes the signing secret, shown only this once.

BodyDescription
urlrequiredhttps URLYour endpoint.
eventsstring[]Events to receive. Defaults to all of them.
{
  "id": "wh_q8Zr1m",
  "url": "https://yourapp.com/webhooks/bugle",
  "events": ["post.published", "post.failed", "account.reauthorization_required"],
  "createdAt": "2026-11-03T14:40:00.000Z",
  "secret": "whsec_mT4k9…"
}

List webhooks

GET/v1/webhooks

Your endpoints, without their secrets.

Delete webhook

DELETE/v1/webhooks/:id

Stops deliveries to the endpoint right away.

Send test event

POST/v1/webhooks/:id/test

Queues a signed webhook.test event to the endpoint so you can check your handler.

{ "queued": true, "eventId": "evt_3Lk9qPz" }

List your apps

GET/v1/platform-apps

Platforms where you saved your own app. Secrets are never returned.

{
  "data": [
    {
      "platform": "x",
      "clientId": "V2tLc3FhN…",
      "createdAt": "2026-11-02T10:00:00.000Z",
      "callbackUrl": "https://api.bugle.pro/v1/connect/x/callback"
    }
  ]
}

Save your app

PUT/v1/platform-apps/:platform

Saves or replaces your client ID and secret for an OAuth platform. New connections use it right away.

BodyDescription
clientIdrequiredstringFrom the platform's developer console.
clientSecretrequiredstringStored encrypted.
{
  "platform": "x",
  "clientId": "V2tLc3FhN…",
  "callbackUrl": "https://api.bugle.pro/v1/connect/x/callback"
}

Remove your app

DELETE/v1/platform-apps/:platform

New connections go back to Bugle's app, if the platform has one. Accounts connected through your app may stop refreshing, so reconnect them.

Copied