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.
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.
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.
A missing or wrong key returns 401 with the code unauthorized.
# Recommended x-api-key: sk_live_xxxxxxxxxxxx # Also accepted Authorization: Bearer sk_live_xxxxxxxxxxxx
Conventions
- Base URL:
https://api.bugle.pro. All endpoints live under/v1. - JSON in, JSON out. Send
content-type: application/jsonwith 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 anextCursorfor paging. - Deletes return
204 No Content, except cancelling a post, which returns the cancelled post.
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.
| Status | Code | When |
|---|---|---|
| 400 | bad_request | The body or query is malformed. details lists each field as { path, message }. |
| 400 | platform_not_configured | The platform has no app on this server yet, or needs your own app. |
| 400 | connect_failed | Credentials were rejected, for example a wrong Bluesky app password. |
| 401 | unauthorized | Missing or invalid API key. |
| 403 | forbidden | An upload URL is invalid or has expired. |
| 404 | not_found | The resource does not exist in this project. |
| 409 | conflict | The action does not fit the current state, like rescheduling a published post. |
| 422 | validation_failed | The post breaks a platform rule. details lists the problems per account. |
| 429 | rate_limited | Too many requests. See rate limits. |
| 502 | platform_error | The social platform returned an error. |
| 500 | internal_error | Something 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"]
}
]
}
}
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.
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.
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.
- Call Start OAuth with an optional
profileIdand theredirectUrlof a page in your app. - Send the user to the returned
url. It is valid for 10 minutes. - After approval the platform returns to Bugle, Bugle stores the tokens (encrypted) and then redirects to your
redirectUrlwith the result in the query string.
| Query parameter | Value |
|---|---|
status | success or error |
platform | For example linkedin |
accountIds | Comma-separated new account IDs (on success). Facebook can return several Pages at once. |
profileId | The profile the accounts were added to (on success) |
error | What 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
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": trueor no time at all: queued right away."scheduledFor": "2026-11-05T09:30:00+03:00": published at that moment. Addtimezone(an IANA name likeEurope/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 status | Meaning |
|---|---|
| queued | Waiting to be published, usually for a few seconds. |
| scheduled | Will be published at scheduledFor. |
| publishing | Being sent to the platforms right now. |
| published | Every target succeeded. |
| partial | Some targets succeeded, some failed. Check each target's error. |
| failed | No target succeeded. |
| cancelled | You 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.
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:
- Call Create upload URL with the file's MIME type.
PUTthe raw file bytes touploadUrlwith the returned headers. The URL works for one hour.- Use
publicUrlin your post.
Accepted types: image/jpeg, image/png, image/gif, image/webp, video/mp4, video/quicktime.
localhost URLs will fail.curl -X PUT "$UPLOAD_URL" \ -H "content-type: video/mp4" \ --data-binary @launch.mp4
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.
| Event | Sent when | data |
|---|---|---|
post.scheduled | A post was created with a future time | Post |
post.published | Every target succeeded | Post |
post.partial | Some targets failed | Post |
post.failed | Every target failed | Post |
post.cancelled | You cancelled a post | Post |
account.connected | An account was connected | Account |
account.reauthorization_required | The account must be connected again | accountId, platform, reason |
account.disconnected | An account was disconnected | accountId, platform |
webhook.test | You 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…"
}
]
}
}
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); }
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.
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.
| Platform | Connect | Text limit | Media | Options (platforms[].options) |
|---|---|---|---|---|
| X | OAuth, your own app | 280 (links count as 23) | Up to 4 images, or 1 video | replyToId |
| OAuth (Business or Creator account) | 2,200 | Required. Up to 20 items as a carousel; videos post as Reels | type: "story" · shareToFeed | |
| Facebook Pages | OAuth | Very long | Up to 10 images, or 1 video on its own | link |
| TikTok | OAuth | 2,200 | Required. 1 video, or up to 35 images | privacyLevel (required) · userConsent: true (required) · disableComment · disableDuet · disableStitch · brandContent · brandOrganic · mode: "inbox" |
| YouTube | OAuth | Title 100, description 5,000 | Exactly 1 video | title (else the first line) · privacyStatus · tags · categoryId · madeForKids · short |
| OAuth | 3,000 | Up to 9 images (no video yet) | visibility: "PUBLIC" or "CONNECTIONS" · link | |
| Threads | OAuth | 500 | Up to 20 items as a carousel | None |
| OAuth | Description 800, title 100 | Exactly 1 image (no video yet) | boardId (required) · title · link | |
| Bluesky | App password | 300 | Up 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
Every endpoint, with its parameters and a real response.
List platforms
The platforms this server supports and whether you can connect them right now.
| Field | Description |
|---|---|
| availableboolean | Accounts can be connected now. |
| byokRequiredboolean | You must save your own app first (X). |
| auth"oauth2" | "credentials" | Which connect flow to use. |
| callbackUrlstring | For 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
Creates a profile for one of your users or clients.
| Body | Description |
|---|---|
| namerequiredstring, max 200 | A label you'll recognise. |
| externalIdstring, max 200 | The 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
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
Deletes an empty profile. If it still has connected accounts you get 409 conflict; disconnect them first.
Start OAuth
Returns the platform's sign-in URL. Send the user there. See Connecting accounts for the whole flow.
| Query | Description |
|---|---|
| profileIdstring | Profile to add the account to. Defaults to the default profile. |
| redirectUrlURL | Where 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
Connects a Bluesky account with an app password. The password is used once to start a session and is not stored.
| Body | Description |
|---|---|
| identifierrequiredstring | Handle (name.bsky.social) or email. |
| appPasswordrequiredstring | An app password, never the main password. |
| profileIdstring | Profile to add the account to. |
| serviceURL | For 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
Connected accounts, oldest first. Disconnected accounts are left out. Get one with GET /v1/accounts/:id. Tokens are never returned.
| Query | Description |
|---|---|
| profileIdstring | Only this profile's accounts. |
| platformstring | Only 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
Deletes the stored tokens and hides the account. Scheduled posts that target it will fail. Sends account.disconnected.
Account resources
Reads platform data you need before posting.
| Name | Returns |
|---|---|
| boardsPinterest | The user's boards: id, name, privacy. |
| creator-infoTikTok | TikTok'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
Returns a one-hour URL to PUT a file to, and the public URL to use in posts.
| Body | Description |
|---|---|
| mimeTyperequiredstring | One of the accepted types. |
| filenamestring, max 255 | Original 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
Deletes an uploaded file. Posts already published keep their copy on the platform.
Create post
Validates the post for every target, then queues or schedules it. See Publishing and scheduling.
| Body | Description |
|---|---|
| platformsrequiredarray, 1–50 | The targets. Each account may appear once. |
| platforms[].accountIdrequiredstring | An active account in this project. |
| platforms[].contentstring | Text for this account only. |
| platforms[].optionsobject | Platform options, like a YouTube title. |
| contentstring, max 10,000 | The text. Can be empty if there is media. |
| mediaItemsarray, max 35 | { url, type: "image" | "video", altText? }, in order. |
| publishNowboolean | Queue right away (the default when there is no time). |
| scheduledForISO 8601 with offset | When to publish. Cannot be combined with publishNow. |
| timezonestring | IANA 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
Posts in the project, newest first.
| Query | Description |
|---|---|
| statusstring | Only posts with this status. |
| limit1–100, default 20 | Page size. |
| beforepost ID | Pass 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
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
Moves a scheduled post to a new future time. Other statuses return 409 conflict.
| Body | Description |
|---|---|
| scheduledForrequiredISO 8601 with offset | The new time. Must be in the future. |
| timezonestring | IANA time zone. |
Cancel post
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
Registers an endpoint. The response includes the signing secret, shown only this once.
| Body | Description |
|---|---|
| urlrequiredhttps URL | Your 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
Your endpoints, without their secrets.
Delete webhook
Stops deliveries to the endpoint right away.
Send test event
Queues a signed webhook.test event to the endpoint so you can check your handler.
{ "queued": true, "eventId": "evt_3Lk9qPz" }
List your 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
Saves or replaces your client ID and secret for an OAuth platform. New connections use it right away.
| Body | Description |
|---|---|
| clientIdrequiredstring | From the platform's developer console. |
| clientSecretrequiredstring | Stored encrypted. |
{
"platform": "x",
"clientId": "V2tLc3FhN…",
"callbackUrl": "https://api.bugle.pro/v1/connect/x/callback"
}
Remove your app
New connections go back to Bugle's app, if the platform has one. Accounts connected through your app may stop refreshing, so reconnect them.