Developer Documentation | SocialBu

SocialBu API documentation

Use your access token from Settings → API for Developers to authenticate API requests.

Get API token

API docs by Redocly](https://redocly.com/redoc/)

SocialBu API (1.0.0)

Download OpenAPI specification: SocialBu API

E-mail: support@socialbu.comTerms of Service

This is documentation for the SocialBu API.

Base URL: https://socialbu.com/api/v1

Authentication: For authenticated endpoints, send your API access token in the Authorization header using the Bearer format: Authorization: Bearer YOUR_API_TOKEN

You can get your API token from Settings in your SocialBu dashboard. You can also generate one programmatically by calling POST /auth/get_token with your email and password.

tag/Authentication Authentication

Authenticate api requests

tag/Authentication/operation/logout Destroy current access token

Logs you out by destroying your access token.

Authorizations:

HTTP: bearerAuth

Responses

200

Logged out successfully.

400

Bad Request

post/auth/logout

SocialBu API

https://socialbu.com/api/v1/auth/logout

Response samples

Content type

application/json

Copy

`{"success": true

}`

tag/Authentication/operation/discoverApi Discover the SocialBu API

Returns links to the API documentation, OpenAPI specification, authentication endpoint, and MCP server.

Responses

200

API discovery information

429

Too many requests

get/

SocialBu API

https://socialbu.com/api/v1/

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"name": "string",

"version": "string",

"documentation": "http://example.com",

"openapi": "http://example.com",

"authentication": {"type": "string",

"token_endpoint": "http://example.com"

},

"mcp": "http://example.com"

}`

tag/Authentication/operation/getToken Get access token for authentication of requests

Generates an access token for API authentication.

Authorizations:

None

Request Body schema: application/json
email
required		 string
User's email address e.g, ( user@example.com)
password
required		 string
User's password.

Responses

200

Access token

400

Bad Request

422

The given data was incorrect.

post/auth/get_token

SocialBu API

https://socialbu.com/api/v1/auth/get\_token

Request samples

Content type

application/json

Copy

`{"email": "string",

"password": "string"

}`

Response samples

Content type

application/json

Copy

`{"authToken": "string",

"id": 0,

"name": "string",

"email": "string",

"verified": true

}`

tag/Posts Posts

Manage your posts

tag/Posts/operation/createPost Create a new post.

Creates a new post for one or more social media accounts. Each network has its own optional options object — refer to the network-specific request schemas below.

To attach media, first upload it via /upload_media or /upload_media_by_url and include the returned upload_token in existing_attachments.

This endpoint also supports a queue shortcut:

Authorizations:

HTTP: bearerAuth

Request Body schema: application/json

Any of

FacebookPostRequestInstagramPostRequestXPostRequestThreadsPostRequestLinkedinPostRequestRedditPostRequestMastodonPostRequestPinterestPostRequestGoogleBusinessProfilePostRequestYoutubePostRequestTiktokPostRequestBlueskyPostRequest
accounts
required		 Array of integers
ID(s) of one or more social media accounts.
publish_at
required		 string
Example: "2025-04-14 15:30:00"
Format should be Y-m-d H:i:s (UTC)
content string
The content for the post.
draft boolean
Save the post as a draft
existing_attachments Array of objects (UploadedMediaTokenAttachment)
Attachments already uploaded to SocialBu's storage using media upload endpoint.
options object
Additional options for the post.
postback_url string
Receive postback at this URL if needed. Sends a JSON POST request with parameters post_id, account_id, and status (created, published, failed).
queue_ids Array of integers
If provided, the post will be added to the specified queues.
tags Array of integers <= 10 items
ID(s) of existing tags to apply to the post (maximum 10). Use GET /tags to list available tags and POST /tags to create new ones. Not supported together with queue_id/queue_ids — a queued post has no tag scope until it's actually published, so sending tags alongside either is rejected.
team_id integer
Team Id of social media account.

Responses

200

Post created or saved to queue.

400

Bad Request

422

The given data was invalid.

post/posts

SocialBu API

https://socialbu.com/api/v1/posts

Request samples

Content type

application/json

Example

FacebookPostRequestInstagramPostRequestXPostRequestThreadsPostRequestLinkedinPostRequestRedditPostRequestMastodonPostRequestPinterestPostRequestGoogleBusinessProfilePostRequestYoutubePostRequestTiktokPostRequestBlueskyPostRequestFacebookPostRequest

Copy Expand all Collapse all

`{"accounts": [0

],

"publish_at": "2025-04-14 15:30:00"

}`

Response samples

Content type

application/json

Copy

`{"message": "Successfully saved to queue"

}`

tag/Posts/operation/bulkDeletePosts Delete multiple posts

Deletes multiple accessible posts by ID.

Authorizations:

HTTP: bearerAuth

Request Body schema: application/json required
ids
required		 Array of integers
IDs of posts to delete.

Responses

200

Posts deleted successfully. Response body is empty.

400

Bad Request

500

Server error while deleting one of the posts

post/posts/bulk_delete

SocialBu API

https://socialbu.com/api/v1/posts/bulk\_delete

Request samples

Content type

application/json

Copy Expand all Collapse all

`{"ids": [0

]

}`

tag/Posts/operation/deletePost Deletes the post

Deletes a scheduled, draft, or published post. Published posts are only deleted from SocialBu — they are not removed from the social network.

Authorizations:

HTTP: bearerAuth

path Parameters
postId
required		 integer
Post id to delete

Responses

200

Post deleted successfully. Response body is empty.

400

Bad Request

404

Resource not found

500

Server error while deleting the post

delete/posts/{postId}

SocialBu API

https://socialbu.com/api/v1/posts/{postId}

tag/Posts/operation/getPost Find post by ID

Returns the full details of a single post, including its content, scheduled time, account associations, publish result, current status, and reviewed_by with id, name, and action (approved or rejected) when approval metadata is available.

Authorizations:

HTTP: bearerAuth

path Parameters
postId
required		 integer
ID of post to return

Responses

200

Post found

400

Bad Request

404

Resource not found

405

Validation exception

get/posts/{postId}

SocialBu API

https://socialbu.com/api/v1/posts/{postId}

Response samples

Content type

application/json

Copy

{ }

tag/Posts/operation/getSupportedOptions Get supported post options for accounts

Returns the raw publish handler option definitions for the specified accounts or all available accounts. Each option includes its type, label, constraints, and available choices.

Authorizations:

HTTP: bearerAuth

query Parameters
account_ids string
Example: account_ids=1,2,3
Comma-separated list of account IDs to get options for. If omitted, returns options for all available accounts.

Responses

200

Supported options retrieved successfully

404

No matching accounts found

get/posts/supported-options

SocialBu API

https://socialbu.com/api/v1/posts/supported-options

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"success": true,

"accounts": [{"account_id": 0,

"account_type": "string",

"account_name": "string",

"options": {"property1": {"label": "string",

"type": "boolean",

"storage": "file",

"required": true,

"default": null,

"max_length": 0,

"options": [{"value": "string",

"label": "string"

}

]

},

"property2": {"label": "string",

"type": "boolean",

"storage": "file",

"required": true,

"default": null,

"max_length": 0,

"options": [{"value": "string",

"label": "string"

}

]

}

}

}

]

}`

tag/Posts/operation/getPosts List posts

Returns a paginated list of posts filtered by their status. Use the type parameter to fetch scheduled, draft, awaiting-approval, or published posts. Reviewed post objects include reviewed_by with id, name, and action (approved or rejected) when approval metadata is available.

Authorizations:

HTTP: bearerAuth

query Parameters
accounts Array of integers
Limit results to specific account IDs.
end string
Filter posts on or before this date.
include_post integer
Include a specific post ID in the result set when relevant to the UI flow.
page integer
Page number to fetch.
perPage integer <= 100
Number of posts per page. Maximum 100.
q string
Free-text search query.
source string
Filter by post source.
start string
Filter posts on or after this date.
tags Array of integers
Limit results to posts having any of these tag IDs. Send either a comma-separated list (tags=1,2) or the repeated tags[]=1&tags[]=2 form.
team integer
Limit results to a specific team ID.
type string
Default: "scheduled_or_awaiting_approval"
Enum:"awaiting_approval""draft""published""scheduled""scheduled_or_awaiting_approval"
The type of posts you want to fetch
user integer
Limit results to posts created by a specific user ID.

Responses

200

Get Posts

400

Bad Request

422

The given data was invalid.

get/posts

SocialBu API

https://socialbu.com/api/v1/posts

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"items": [{ }

],

"currentPage": 0,

"lastPage": 0,

"nextPage": 0,

"total": 0

}`

tag/Posts/operation/publishPostNow Publish a post now

Converts the post to a non-draft, sets its publish time to now, clears any previous publish result, and triggers publishing immediately or queues it for publishing.

Authorizations:

HTTP: bearerAuth

path Parameters
postId
required		 integer
Post id to publish immediately

Responses

200

Post publish triggered successfully

400

Bad Request

404

Resource not found

post/posts/{postId}/publish

SocialBu API

https://socialbu.com/api/v1/posts/{postId}/publish

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"success": true,

"post": {"draft": true,

"approved": true,

"publish_at": "string",

"_published": true

}

}`

tag/Posts/operation/updatePost Update the post

Updates a scheduled or draft post. Only the fields you provide are changed.

Use this endpoint to update post content, schedule, draft state, processed network-specific options, attachments, or review status.

Attachment updates are handled through existing_attachments:

To approve or reject a post awaiting team approval, use the approved field. To publish immediately without editing other fields, send publish_now=true. Reviewed post objects returned by this endpoint include reviewed_by with id, name, and action (approved or rejected) when approval metadata is available.

Authorizations:

HTTP: bearerAuth

path Parameters
postId
required		 integer
Post id to update
Request Body schema: application/jsonmultipart/form-dataapplication/json
approved boolean
Approve or reject a post awaiting team approval.
Set to true to approve, false to reject.
Requires the approvals.approve permission in the team.
content string or null
Updated post content. Can be null when the target network allows attachment-only posts.
draft boolean
Set to true to keep the post as a draft, or false to make it schedulable/publishable.
existing_attachments Array of UploadedMediaTokenAttachment (object) or SavedPostAttachment (object) (PostUpdateExistingAttachment)
Final attachment set for the post. This array accepts both newly uploaded media token objects
and already-saved attachment objects returned by GET /posts/{postId}.
Any previously attached media omitted from this array is removed. To keep an already-saved attachment,
send back its full object including path. You can also send newly uploaded files with the same
request using multipart form-data attachments[].
from string
Value:"composer"
Special composer mode. When set to composer, omitted options and existing_attachments
are treated as empty arrays so removed values are cleared from the saved post.
options object
Public post options to update for the post's connected account. These are processed and merged with
the post's internal options instead of replacing the entire stored options object. Supported keys vary
by network and account type; use GET /posts/supported-options to discover valid fields.
publish_at string
Example: "2025-04-14 15:30:00"
New scheduled time in Y-m-d H:i:s UTC format. If a past time is sent, the server shifts it to the current time.
publish_now boolean
Publish the post immediately instead of applying a regular partial update.
reject_reason string
Optional reason when rejecting a post (approved=false). Visible to the post author.
reset_result boolean
Set to true to clear the stored publish result before republishing or rescheduling.
tags Array of integers <= 10 items
ID(s) of existing tags to apply to the post (maximum 10, same scope rules as on create — see POST /posts). Omit this field entirely to leave the post's tags unchanged. Send an empty array to clear every tag.

Responses

200

Post updated

400

Bad Request

404

Resource not found

422

The given data was invalid.

patch/posts/{postId}

SocialBu API

https://socialbu.com/api/v1/posts/{postId}

Request samples

Content type

application/jsonmultipart/form-dataapplication/json

Copy

{ }

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"success": true,

"post": { }

}`

tag/Tags Tags

Manage tags for posts or the inbox (post and inbox tags are independent).

tag/Tags/operation/createTag Create a tag

Creates a new tag, either personal or scoped to a team. A team type=post tag requires posts.create or posts.edit; a team type=inbox tag requires inbox.manage.

Authorizations:

HTTP: bearerAuth

Request Body schema: application/json required
name
required		 string [ 2 .. 50 ] characters
type
required		 string
Enum:"inbox""post"
Whether this is a post tag or an inbox tag. Tags are no longer shared between the two.
color string or null^#[0-9A-Fa-f]{6}$
Hex color. Any valid 6-digit hex color is accepted. Omit for the default (uncolored) look.
team_id integer
Team ID to create the tag under. Omit to create a personal tag.

Responses

200

Tag created successfully.

400

Tag already exists.

403

You do not have permission to create a tag for this team.

422

Validation failed (e.g. missing/invalid type, or color not a valid #RRGGBB hex string).

post/tags

SocialBu API

https://socialbu.com/api/v1/tags

Request samples

Content type

application/json

Copy

`{"name": "string",

"type": "inbox"

}`

Response samples

Content type

application/json

Copy

`{"message": "string",

"tag": "string",

"id": 0,

"color": "string",

"can_manage": true

}`

tag/Tags/operation/deleteTag Delete a tag

Deletes the tag and removes it from any posts or inbox conversations it was applied to. For a team tag this requires posts.edit (type=post) or inbox.manage (type=inbox).

Authorizations:

HTTP: bearerAuth

path Parameters
id
required		 integer
Tag ID.

Responses

200

Tag deleted successfully.

404

Tag not found.

delete/tags/{id}

SocialBu API

https://socialbu.com/api/v1/tags/{id}

tag/Tags/operation/listTags List tags

Returns tags available to the authenticated user. Pass team_id to list a team's tags — requires any of posts.view, posts.create or posts.edit for type=post, or inbox.manage for type=inbox. Omit team_id to list your personal tags.

Authorizations:

HTTP: bearerAuth

query Parameters
team_id integer
Team ID to scope the tag list to. Omit to list personal tags.
type
required		 string
Enum:"inbox""post"
Which set of tags to list — post tags or inbox tags. Tags are no longer shared between the two.

Responses

200

Tag list

403

You do not have permission to access this team's tags.

get/tags

SocialBu API

https://socialbu.com/api/v1/tags

Response samples

Content type

application/json

Copy Expand all Collapse all

[{"id": 0,\ \ "name": "string",\ \ "color": "string",\ \ "type": "inbox",\ \ "user_id": 0,\ \ "team_id": 0,\ \ "conversations_count": 0,\ \ "can_manage": true\ \ }\ \ ]

tag/Tags/operation/updateTag Rename a tag

Renames or recolors a tag. For a team tag this requires posts.edit (type=post) or inbox.manage (type=inbox).

Authorizations:

HTTP: bearerAuth

path Parameters
id
required		 integer
Tag ID.
Request Body schema: application/json required
name
required		 string [ 2 .. 50 ] characters
color string or null^#[0-9A-Fa-f]{6}$
Hex color. Any valid 6-digit hex color is accepted. Omit to leave the current color unchanged.

Responses

200

Tag updated successfully.

400

Tag already exists.

404

Tag not found.

patch/tags/{id}

SocialBu API

https://socialbu.com/api/v1/tags/{id}

Request samples

Content type

application/json

Copy

`{"name": "string"

}`

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"message": "string",

"tag": {"id": 0,

"name": "string",

"color": "string",

"type": "inbox",

"user_id": 0,

"team_id": 0,

"conversations_count": 0,

"can_manage": true

}

}`

tag/Queues Queues

Manage your publishing queues and queue items.

tag/Queues/operation/createQueuePost Add a post to a queue

Validates the post for the selected accounts, then stores it in the queue.

Authorizations:

HTTP: bearerAuth

path Parameters
id
required		 integer
Queue ID.
Request Body schema: application/json required
accounts
required		 Array of integers
ID(s) of one or more social media accounts used to validate queue post options.
content string
The content to save into the queue.
existing_attachments Array of objects (UploadedMediaTokenAttachment)
Attachments already uploaded to SocialBu's storage using media upload endpoint.
options object
Queue post options. Can be a shared options object or keyed by account ID.

Responses

204

Queue post created successfully.

400

Bad Request

404

Queue not found

422

The given data was invalid.

post/queues/{id}/posts

SocialBu API

https://socialbu.com/api/v1/queues/{id}/posts

Request samples

Content type

application/json

Copy Expand all Collapse all

`{"accounts": [0

]

}`

tag/Queues/operation/listQueues List available queues

Returns all queues available to the authenticated user, including team queues they can access.

Authorizations:

HTTP: bearerAuth

Responses

200

Queue list

400

Bad Request

get/queues

SocialBu API

https://socialbu.com/api/v1/queues

Response samples

Content type

application/json

Copy Expand all Collapse all

[{"id": 0,\ \ "name": "string",\ \ "user_id": 0,\ \ "user_name": "string",\ \ "options": { },\ \ "team_id": 0,\ \ "active": true,\ \ "times_to_publish": 0,\ \ "next_publish_at": "string",\ \ "started_at": "string",\ \ "ended_at": "string",\ \ "created_at": "string",\ \ "updated_at": "string",\ \ "need_cleanup": true\ \ }\ \ ]

tag/Queues/operation/listQueuePosts List queue posts

Returns paginated posts for a single queue.

Authorizations:

HTTP: bearerAuth

path Parameters
id
required		 integer
Queue ID.
query Parameters
perPage integer <= 500
Number of items per page. Maximum 500.

Responses

200

Queue posts

404

Queue not found

422

The given data was invalid.

get/queues/{id}/posts

SocialBu API

https://socialbu.com/api/v1/queues/{id}/posts

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"items": [{ }

],

"currentPage": 0,

"lastPage": 0,

"nextPage": 0,

"total": 0,

"nextItemId": 0,

"nextPublishTime": "string"

}`

tag/Queues/operation/shuffleQueue Shuffle queue order

Randomizes the order of items in the queue.

Authorizations:

HTTP: bearerAuth

path Parameters
id
required		 integer
Queue ID.

Responses

204

Queue shuffled successfully.

404

Queue not found

post/queues/{id}/shuffle

SocialBu API

https://socialbu.com/api/v1/queues/{id}/shuffle

tag/Media-Upload Media Upload

Upload media files to your posts.

Option A — Three-step signed URL flow:

  1. Get a signed URL for direct media upload to SocialBu's storage using POST /upload_media.
  2. Use the signed_url from Step 1 to upload your actual file (video/image) directly to SocialBu's storage.
  3. Once the file is uploaded, confirm its status using the media key returned in Step 1 via /upload_media/status.

Now that the media is uploaded and verified, you can attach this file to your post using the upload_token recieved in Step 3.

Option B — Single-step URL or data URL upload: Use POST /upload_media_by_url with an HTTP(S) URL or a base64 data URL. The server stores the file and returns an upload_token directly in one step — no signed URL or status check needed.

tag/Media-Upload/operation/checkMediaStatus Check media upload status

Checks whether a media file has finished uploading to SocialBu's storage. Once success is true, use the returned upload_token in existing_attachments when creating a post.

Authorizations:

HTTP: bearerAuth

query Parameters
key string
The key value returned in /upload_media endpoint.

Responses

200

File status

400

Bad Request

422

The given data was invalid.

get/upload_media/status

SocialBu API

https://socialbu.com/api/v1/upload\_media/status

Response samples

Content type

application/json

Copy

`{"success": true,

"message": "string",

"upload_token": "string"

}`

tag/Media-Upload/operation/uploadMediaFile Initiate media upload

Generate a pre-signed URL to upload a media file.

Authorizations:

HTTP: bearerAuth

Request Body schema: application/json

Send the file name and MIME type to generate a pre-signed URL and key.
mime_type
required		 string
File type e.g, ("application/pdf" ,"image/png")
name
required		 string
File name e.g, ("document.pdf" ,"image.png")

Responses

200

file uploaded

422

The given data was invalid.

post/upload_media

SocialBu API

https://socialbu.com/api/v1/upload\_media

Request samples

Content type

application/json

Copy

`{"name": "string",

"mime_type": "string"

}`

Response samples

Content type

application/json

Copy

`{"name": "string",

"mime_type": "string",

"signed_url": "string",

"key": "string",

"secure_key": "string",

"url": "string"

}`

tag/Media-Upload/operation/uploadMediaByUrl Upload media by URL

Upload a media file by providing an HTTP(S) URL or a base64 data URL. The server downloads HTTP(S) URLs and stores data URLs directly, returning an upload_token in a single step.

This is simpler than the three-step signed URL flow — no separate upload or status check is needed. The upload_token returned can be used in existing_attachments when creating a post, the same as the token from the three-step flow.

Supported file types: jpg, jpeg, png, gif, webp, mp4, mov, avi, webm, mkv, pdf. The maximum decoded file size is about 56 MiB. Base64 data URL payloads are limited to 75 MiB.

Authorizations:

HTTP: bearerAuth

Request Body schema: application/json required

HTTP(S) URL or base64 data URL of the media file, with an optional custom filename.
url
required		 string <= 78643264 characters
HTTP(S) URL to download or a base64 data URL. Base64 payloads are limited to 75 MiB.
name string <= 255 characters
Custom filename for the stored file. If not provided, the filename is extracted from the URL.

Responses

200

File uploaded successfully.

400

Bad Request. Possible reasons — file too large (about 56 MiB decoded, or 75 MiB base64 payload), unsupported file type, empty file, invalid data URL, download failed, URL not found, or access denied.

422

The given data was invalid. The url field is missing or malformed.

500

Internal server error.

post/upload_media_by_url

SocialBu API

https://socialbu.com/api/v1/upload\_media\_by\_url

Request samples

Content type

application/json

Copy

`{"url": "string"

}`

Response samples

Content type

application/json

Copy

`{"success": true,

"message": "string",

"name": "string",

"mime_type": "string",

"size": 0,

"key": "string",

"upload_token": "string",

"url": "string"

}`

tag/Accounts Accounts

Manage your social accounts

tag/Accounts/operation/connectAccount Connect a new social account

Initiates the OAuth connection flow for a new social media account. Returns a connect_url that should be opened in a browser popup. Optionally provide a postback_url to receive a webhook notification when the connection completes.

Authorizations:

HTTP: bearerAuth

Request Body schema: application/json
provider
required		 string
Social media network name e.g, (Instagram, Twitter etc.)
account_id string
Social account id if reconnecting an existing account.
postback_url string
Receive postback at this URL. Sends a JSON POST request with parameters account_action (added, updated, connected, disconnected), account_id, account_type, and account_name. The account_action is disconnected if an account is found disconnected by the system, connected if a previously disconnected account is reconnected by the system automatically, added when a new account is added/connected for the first time, and updated when an existing account is reconnected.

Responses

200

You get the URL for connecting social accounts. Recommended to open it in a popup.

400

The provider is not supported

post/accounts

SocialBu API

https://socialbu.com/api/v1/accounts

Request samples

Content type

application/json

Copy

`{"provider": "string"

}`

Response samples

Content type

application/json

Copy

`{"connect_url": "http://example.com"

}`

tag/Accounts/operation/deleteAccount Deletes the social account

Permanently removes a connected social media account. Any scheduled posts associated with this account will also be removed.

Authorizations:

HTTP: bearerAuth

path Parameters
accountId
required		 integer
Account id to delete

Responses

200

Account deleted

404

Resource not found

delete/accounts/{accountId}

SocialBu API

https://socialbu.com/api/v1/accounts/{accountId}

Response samples

Content type

application/json

Copy

`{"message": "string"

}`

tag/Accounts/operation/getAccount Get social account by ID

Returns the full details of a single connected social media account, including its type, name, connection status, and any extra data (e.g. board lists for Pinterest, category IDs for YouTube).

Authorizations:

HTTP: bearerAuth

path Parameters
accountId
required		 integer
Social account id.

Responses

200

Social account found

404

Resource not found

get/accounts/{accountId}

SocialBu API

https://socialbu.com/api/v1/accounts/{accountId}

Response samples

Content type

application/json

Copy

{ }

tag/Accounts/operation/getAccounts Get social accounts

Returns a paginated list of all social media accounts accessible to the authenticated user, including accounts shared via teams.

Authorizations:

HTTP: bearerAuth

query Parameters
type Array of strings
Items Enum:"all""shared""user"
The type of accounts you want to fetch.

Responses

200

Social accounts

422

The given data was invalid.

get/accounts

SocialBu API

https://socialbu.com/api/v1/accounts

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"items": [ ],

"currentPage": 0,

"lastPage": 0,

"nextPage": 0,

"total": 0

}`

tag/Accounts/operation/updateAccount Update the social account

Updates the display name and optional AI context for a connected social media account. The AI context is used only as private background context for SocialBu AI features.

Authorizations:

HTTP: bearerAuth

path Parameters
accountId
required		 integer
Social account id.
Request Body schema: application/json
ai_context string or null <= 2000 characters
Optional AI context for this account, such as brand voice, audience, products, or content goals. Send an empty string to clear it.
name string
New name for the connected social account.

Responses

200

Social account updated

404

The resource not found

422

The given data was invalid.

patch/accounts/{accountId}

SocialBu API

https://socialbu.com/api/v1/accounts/{accountId}

Request samples

Content type

application/json

Copy

{ }

Response samples

Content type

application/json

Copy

`{"message": "string"

}`

tag/Team Team

Manage your teams

tag/Team/operation/createTeam Create a new team.

Creates a new team with the specified accounts and members. Each member can be assigned granular permissions controlling what they can do within the team.

Authorizations:

HTTP: bearerAuth

Request Body schema: application/json
accounts
required		 Array of objects
name
required		 string
Name of the team.
ai_context string or null <= 2000 characters
Optional AI context for this team, such as brand voice, audience, products, or content goals. Used only as private background context for SocialBu AI features.
members Array of objects
requires_content_approval boolean
True if content requires approval before publishing.

Responses

200

successful operation

405

Invalid input

post/teams

SocialBu API

https://socialbu.com/api/v1/teams

Request samples

Content type

application/json

Copy Expand all Collapse all

`{"name": "string",

"accounts": [{ }

]

}`

Response samples

Content type

application/json

Copy

`{"success": true,

"message": "string"

}`

tag/Team/operation/deleteTeam Deletes team.

Permanently deletes a team and removes all member associations.

Authorizations:

HTTP: bearerAuth

path Parameters
teamId
required		 integer
Team id you want to delete.

Responses

200

Resource deleted

delete/teams/{teamId}

SocialBu API

https://socialbu.com/api/v1/teams/{teamId}

Response samples

Content type

application/json

Copy

`{"success": true,

"message": "string"

}`

tag/Team/operation/getTeams Get your teams

Returns a paginated list of teams. Use the type parameter to filter between teams you created and teams you have joined.

Authorizations:

HTTP: bearerAuth

query Parameters
type Array of strings
Items Enum:"created""joined"
The type of team you want to fetch

Responses

200

Teams

400

Bad Request

get/teams

SocialBu API

https://socialbu.com/api/v1/teams

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"items": [{ }

],

"currentPage": 0,

"lastPage": 0,

"nextPage": 0,

"total": 0

}`

tag/Team/operation/updateTeam Update team

Replaces the team's name, accounts, members, and approval settings in full. All fields are required — omitted accounts or members will be removed from the team.

Authorizations:

HTTP: bearerAuth

path Parameters
teamId
required		 integer
Team id you want to update
Request Body schema: application/json
accounts
required		 Array of objects
name
required		 string
Name of the team.
ai_context string or null <= 2000 characters
Optional AI context for this team, such as brand voice, audience, products, or content goals. Send an empty string to clear it.
members Array of objects
requires_content_approval boolean
True if content requires approval before publishing.

Responses

200

resource updated

403

Forbidden — plan limit exceeded or insufficient permissions.

put/teams/{teamId}

SocialBu API

https://socialbu.com/api/v1/teams/{teamId}

Request samples

Content type

application/json

Copy Expand all Collapse all

`{"name": "string",

"accounts": [{ }

]

}`

Response samples

Content type

application/json

Copy

`{"success": true,

"message": "string"

}`

tag/Curation Curation

Access curated content.

tag/Curation/operation/getItem Find curation item by ID

Returns a curation item

Authorizations:

HTTP: bearerAuth

path Parameters
id
required		 integer
ID of item to return

Responses

200

successful operation

404

Resource not found

get/curation/items/{id}

SocialBu API

https://socialbu.com/api/v1/curation/items/{id}

Response samples

Content type

application/json

Copy

`{"id": 0,

"feed_id": 0,

"title": "string",

"link": "string",

"description": "string",

"media": "string",

"published_at": "2019-08-24T14:15:22Z",

"authors": "string",

"tags": "string",

"score": 0

}`

tag/Curation/operation/getCurationEmbedUrl Get a signed embed URL for curated items

Returns a signed embed URL and iframe code for the current curation filters so the result set can be embedded in dashboards, portals, or websites.

Authorizations:

HTTP: bearerAuth

query Parameters
authors Array of strings
The list of authors
feed_id integer
The feed id
from string
Fixed start date. Format should be Y-m-d. Overrides time_range when provided.
search string
Search curated item content by meaning.
sort string
Enum:"newest""oldest""relevance"
Sort order for vector search results. Only applies when search is provided. Defaults to relevance.
source_scope string
Enum:"all""global""private""team"
Filter by source visibility. Use team with team_id to search a specific team source set.
team_id integer
Team id used when source_scope is team.
time_range string
Enum:"last_14_days""last_30_days""last_3_months""last_7_days"
Rolling time range to use when from/to are not provided.
to string
Fixed end date. Format should be Y-m-d. Overrides time_range when provided.

Responses

200

successful operation

405

Validation exception

get/curation/embed-url

SocialBu API

https://socialbu.com/api/v1/curation/embed-url

Response samples

Content type

application/json

Copy

`{"url": "http://example.com",

"embed_code": "string"

}`

tag/Curation/operation/getCurationRssUrl Get a signed RSS URL for curated items

Returns a signed RSS URL for the current curation filters so the result set can be used in RSS readers or third-party systems.

Authorizations:

HTTP: bearerAuth

query Parameters

Responses

200

successful operation

405

Validation exception

get/curation/rss-url

SocialBu API

https://socialbu.com/api/v1/curation/rss-url

Response samples

Content type

application/json

Copy

`{"url": "http://example.com"

}`

tag/Curation/operation/getItems Get curation items

Returns a list curation items

Authorizations:

HTTP: bearerAuth

query Parameters
authors Array of strings
The list of authors
feed_id integer
The feed id
from string
Fixed start date. Format should be Y-m-d. Overrides time_range when provided.
layout string
Enum:"cards""rows"
Presentation layout for the iframe.
page integer
The page number
per_page integer
The number of items per page
search string
Search curated item content by meaning.
sort string
Enum:"newest""oldest""relevance"
Sort order for vector search results. Only applies when search is provided. Defaults to relevance.
source_scope string
Enum:"all""global""private""team"
Filter by source visibility. Use team with team_id to search a specific team source set.
team_id integer
Team id used when source_scope is team.
time_range string
Enum:"last_14_days""last_30_days""last_3_months""last_7_days"
Rolling time range to use when from/to are not provided.
to string
Fixed end date. Format should be Y-m-d. Overrides time_range when provided.

Responses

200

successful operation id, feed_id, title, link, description, media, published_at, authors, tags, score.

400

Bad Request

404

Resource not found

405

Validation exception

get/curation/items

SocialBu API

https://socialbu.com/api/v1/curation/items

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"items": [{"id": 0,

"feed_id": 0,

"title": "string",

"link": "string",

"description": "string",

"media": "string",

"published_at": "2019-08-24T14:15:22Z",

"authors": "string",

"tags": "string",

"score": 0

}

],

"currentPage": 0,

"lastPage": 0,

"nextPage": 0,

"total": 0

}`

tag/Curation/operation/getTopics Get curation search suggestions.

Returns a flat list of search autocomplete suggestions. Suggestions may be personalized from recent team/account activity when available.

Authorizations:

HTTP: bearerAuth

query Parameters
q string
Search suggestion text for autocomplete suggestions.

Responses

200

successful operation

400

Bad Request

404

Resource not found

405

Validation exception

get/curation/topics

SocialBu API

https://socialbu.com/api/v1/curation/topics

Response samples

Content type

application/json

Copy Expand all Collapse all

[{"id": "string",\ \ "name": "string",\ \ "items_count": 0\ \ }\ \ ]

tag/Insights Insights

Get valuable insights about your account's content.

tag/Insights/operation/getAutomationLogs Get automation logs.

Returns the latest activity logs for all automations the user has access to.

Authorizations:

HTTP: bearerAuth

query Parameters
limit integer [ 1 .. 100 ]
Default: 5
Maximum number of automation logs to return.

Responses

200

successful operation

404

Resource not found

get/insights/automations/logs

SocialBu API

https://socialbu.com/api/v1/insights/automations/logs

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"data": [{"id": 0,

"title": "string",

"description": "string",

"timestamp": "string",

"created_at": "2019-08-24T14:15:22Z"

}

]

}`

tag/Insights/operation/getEngagementTrend Get engagement trend over time.

Returns the daily total engagements across all accessible accounts within the specified date range.

Uses the same engagement metric types as /insights/accounts/engagement/rate: likes, comments, reactions, shares, replies, retweets, quote_tweets, reblogs, favourites, total_interactions, score, saved, reposts, quotes, pin_clicks, bookmarks.

Data is aggregated from post metrics across all networks that support post-level tracking: Facebook Page, Instagram, Twitter/X, LinkedIn (Org, Brand, Profile), YouTube, Pinterest, Threads, Bluesky, Mastodon, Reddit. TikTok and Google Business Location do not contribute (no post metrics tracked).

Authorizations:

HTTP: bearerAuth

query Parameters
end
required		 string
The end date
start
required		 string
The start date

Responses

200

successful operation

404

Resource not found

422

Validation error

get/insights/accounts/engagement/trend

SocialBu API

https://socialbu.com/api/v1/insights/accounts/engagement/trend

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"data": [{"date": "2019-08-24",

"engagements": 0

}

],

"last_fetched_at": "2019-08-24T14:15:22Z"

}`

tag/Insights/operation/getAllFollowers Get followers count for all accounts.

Returns the total followers count across all accessible accounts and followers count per account.

Covers all networks that track an audience size metric: Instagram, Twitter/X, TikTok, Bluesky, Mastodon, Pinterest, LinkedIn Org, LinkedIn Brand, Facebook Page, YouTube, Threads.

Authorizations:

HTTP: bearerAuth

Responses

200

successful operation

404

Resource not found

get/insights/accounts/followers

SocialBu API

https://socialbu.com/api/v1/insights/accounts/followers

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"data": {"total_followers": 0,

"followers_by_account": [{"account_id": 0,

"followers": 0,

"last_fetched_at": "2019-08-24T14:15:22Z"

}

],

"last_fetched_at": "2019-08-24T14:15:22Z"

}

}`

tag/Insights/operation/getFollowersGrowth Get followers growth over time.

Returns daily net followers growth (day-over-day change) for all accessible accounts within the specified date range.

Covers the same networks as /insights/accounts/followers: Instagram, Twitter/X, TikTok, Bluesky, Mastodon, Pinterest, LinkedIn Org, LinkedIn Brand, Facebook Page, YouTube, Threads.

Authorizations:

HTTP: bearerAuth

query Parameters
end
required		 string
End date in Y-m-d format.
Date range cannot exceed 90 days.
start
required		 string
Start date in Y-m-d format.

Responses

200

successful operation

404

Resource not found

422

Validation error

get/insights/accounts/followers/growth

SocialBu API

https://socialbu.com/api/v1/insights/accounts/followers/growth

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"data": [{"date": "2019-08-24",

"total_followers": 0

}

],

"last_fetched_at": "2019-08-24T14:15:22Z"

}`

tag/Insights/operation/getOpenConversationsCount Get open conversations count.

Returns the count of open messages in the social inbox for all accessible accounts.

Authorizations:

HTTP: bearerAuth

Responses

200

successful operation

404

Resource not found

get/insights/open-conversations-count

SocialBu API

https://socialbu.com/api/v1/insights/open-conversations-count

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"data": {"open_msgs_count": 0

}

}`

tag/Insights/operation/getPostsCounts Get posts count.

Returns a daily breakdown of published post counts within the given date range. Optionally filter by post type (image, video, text) and by specific accounts or team.

Authorizations:

HTTP: bearerAuth

query Parameters
accounts Array of integers
An array of account IDs.
end
required		 string
The end date
post_type string
Enum:"image""text""video"
The post type that you want to get count against. Default is all.
start
required		 string
The start date
team integer
The team id

Responses

200

successful operation

404

Resource not found

get/insights/posts/counts

SocialBu API

https://socialbu.com/api/v1/insights/posts/counts

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"data": [{"date": "2019-08-24",

"count": 0

}

]

}`

tag/Insights/operation/getUserStats Get stats for the user.

Returns a high-level summary for the authenticated user, including total connected accounts, active automations, scheduled posts, and any accounts with connection errors.

Authorizations:

HTTP: bearerAuth

Responses

200

successful operation

400

Bad Request

404

Resource not found

405

Validation exception

get/insights/stats

SocialBu API

https://socialbu.com/api/v1/insights/stats

Response samples

Content type

application/json

Copy

`{"unreadFeeds": 0,

"userAutomations": 0,

"userPendingPosts": 0,

"userFailedPosts": 0,

"inactiveAccounts": 0

}`

tag/Insights/operation/getTeamActivity Get team activity logs.

Returns the latest activity log entries for all teams the user has access to. Entries include post publications, approvals, rejections, and member actions. Use the limit parameter to control how many entries are returned.

Authorizations:

HTTP: bearerAuth

query Parameters
limit integer [ 1 .. 100 ]
Default: 5
Maximum number of activity logs to return.

Responses

200

successful operation

404

Resource not found

get/insights/teams/activity

SocialBu API

https://socialbu.com/api/v1/insights/teams/activity

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"data": [{"id": 0,

"type": "string",

"title": "string",

"description": "string",

"timestamp": "string",

"created_at": "2019-08-24T14:15:22Z"

}

]

}`

tag/Insights/operation/getTeamsMetrics Get the team metrics

Returns a team's members performance metrics

Authorizations:

HTTP: bearerAuth

query Parameters
accounts Array of integers
An array of account IDs.
end
required		 string
The end date and Format should be Y-m-d.
metrics
required		 string or Array of strings
The metric types you want to fetch. Accepts either a comma-separated string or repeated query parameters such as metrics[]=impressions&metrics[]=engagement.
See /insights/posts/metrics for the full list of supported post metrics per network.
start
required		 string
The start date and Format should be Y-m-d.
team
required		 integer
The team id

Responses

200

successful operation

404

Resource not found

get/insights/teams/metrics

SocialBu API

https://socialbu.com/api/v1/insights/teams/metrics

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"data": [{"member_id": 0,

"member_name": "string",

"member_photo": "string",

"total_engagements": 0,

"scheduled_posts": [{"date": "2019-08-24",

"count": 0

}

],

"published_posts": [{"date": "2019-08-24",

"count": 0

}

],

"rejected_posts": [{"date": "2019-08-24",

"count": 0

}

]

}

]

}`

tag/Insights/operation/getTopPosts Get the top posts

Returns a list of the top posts based on specified metrics

Authorizations:

HTTP: bearerAuth

query Parameters
accounts Array of integers
An array of account IDs.
end
required		 string
The end date and format should be Y-m-d.
metrics
required		 string or Array of strings
The metric types you want to rank posts by. Accepts either a comma-separated string or repeated query parameters such as metrics[]=impressions&metrics[]=engagement.
See /insights/posts/metrics for the full list of supported post metrics per network.
start
required		 string
The start date and format should be Y-m-d.
team integer
The team id

Responses

200

successful operation

404

Resource not found

get/insights/posts/top_posts

SocialBu API

https://socialbu.com/api/v1/insights/posts/top\_posts

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"data": [ ]

}`

tag/Insights/operation/getEngagementRate Get total engagement rate.

Returns the overall engagement rate calculated as (total engagements / total followers) * 100 across all accessible accounts.

Engagement is the sum of all post-level engagement metrics across every post recorded for the account. The following metric types count as engagement: likes, comments, reactions, shares, replies, retweets, quote_tweets, reblogs, favourites, total_interactions, score, saved, reposts, quotes, pin_clicks, bookmarks.

Networks that contribute engagement data (any network with post metrics): Facebook Page (reactions, comments, shares), Instagram (likes, comments, saved, shares, total_interactions, replies), Twitter/X (likes, retweets, quote_tweets, replies, bookmarks), LinkedIn Org/Brand/Profile (likes, comments, shares), YouTube (likes, comments), Pinterest (saved, pin_clicks, reactions, comments), Threads (likes, replies, reposts, quotes), Bluesky (likes, replies, reposts), Mastodon (replies, reblogs, favourites), Reddit (comments, score).

Followers for the denominator are taken from the same audience-size metrics as /insights/accounts/followers

Authorizations:

HTTP: bearerAuth

Responses

200

successful operation

404

Resource not found

get/insights/accounts/engagement/rate

SocialBu API

https://socialbu.com/api/v1/insights/accounts/engagement/rate

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"data": {"total_engagement_rate": 0.1,

"last_fetched_at": "2019-08-24T14:15:22Z"

}

}`

tag/Insights/operation/getAccountsMetrics Get various metrics for accounts within a specified time frame.

Returns date-wise counts of specified metrics for accounts within a given time frame.

Authorizations:

HTTP: bearerAuth

query Parameters

| accounts | Array of integers
An array of account IDs. | | calculate_growth | boolean
Default: true
Whether to return day-over-day deltas from cumulative metric values.
Defaults to true. | | end
required | string
The end date | | metrics
required | string or Array of strings

Examples:

Metric types to fetch. Accepts either a comma-separated string or repeated query parameters such as metrics[]=followers&metrics[]=followers_by_country/*.

Wildcard patterns — some metrics are keyed as {prefix}/{value} where the suffix represents a dimension (country code, age/gender bracket, industry, etc.). You can request all values for a dimension using * as the suffix, or request a single value by providing the exact key:

Pattern What * represents Example exact key
followers_by_country/* ISO 3166-1 alpha-2 country code followers_by_country/US
followers_by_gender_age/* Age bracket + gender code — M, F, or U (Instagram) followers_by_gender_age/25-34_M
fans_by_country/* ISO 3166-1 alpha-2 country code (Facebook) fans_by_country/GB
fan_adds_by_paid_non_paid_unique/* paid or unpaid (Facebook) fan_adds_by_paid_non_paid_unique/paid
followers_by_industry/* LinkedIn industry URN followers_by_industry/urn:li:industry:4
followers_by_function/* LinkedIn job function URN followers_by_function/urn:li:function:8
followers_by_seniority/* LinkedIn seniority URN followers_by_seniority/urn:li:seniority:4
followers_by_staff_count_range/* LinkedIn company size bucket followers_by_staff_count_range/SIZE_11_TO_50
views_by_country/* ISO 3166-1 alpha-2 country code (LinkedIn) views_by_country/DE

Supported account metrics for each network:

Responses

200

successful operation

404

Resource not found

get/insights/accounts/metrics

SocialBu API

https://socialbu.com/api/v1/insights/accounts/metrics

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"data": [{"account_id": 0,

"metrics": {"property1": [{"date": "2019-08-24",

"value": 0

}

],

"property2": [{"date": "2019-08-24",

"value": 0

}

]

},

"latest": [{"type": "string",

"value": 0,

"timestamp": "2019-08-24T14:15:22Z"

}

]

}

]

}`

tag/Insights/operation/getPostsMetrics Get various metrics for posts within a specified time frame.

Returns date-wise post metrics for selected metric types.

Authorizations:

HTTP: bearerAuth

query Parameters
accounts Array of integers
An array of account IDs.
calculate_growth boolean
Default: true
Whether to return day-over-day deltas from cumulative metric values.
Defaults to true.
end
required		 string
The end date
group_by_account boolean
Default: false
Whether to group the response by account.
- false (default): returns summed metrics across selected accounts.
- true: returns metrics per account.
metrics
required		 string or Array of strings
Examples:
- metrics=reach,saved - Instagram reach and saves (all post types)
- metrics=reach,saved,shares,total_interactions - Instagram Reel-specific metrics
- metrics=video_views,impressions,impressions_unique - Facebook video post metrics
- metrics=impressions,likes,comments - Common metrics available across multiple platforms
The metric types you want to fetch. Accepts either a comma-separated string
or repeated query parameters such as metrics[]=impressions&metrics[]=engagement.
Supported post metrics for each network:
- Facebook Page:
- All posts:reactions, comments
- Text posts:shares
- Non-video posts:media_view (impressions), clicks
- Video posts:video_views, video_views_paid, video_views_organic, video_complete_views, video_10s_views, video_avg_time_watched, avg_watch_time, video_view_time, total_plays, replay_count, impressions, impressions_paid, impressions_organic, impressions_fan, impressions_unique
- Stories are not tracked.
- Instagram:
- All posts:likes, comments
- Carousel posts:reach, saved
- Photo posts:reach, saved
- Video posts:reach, saved
- Reel posts:reach, saved, shares, total_interactions
- Story posts:reach, replies
- Twitter / X: bookmarks, retweets, likes, replies, quote_tweets, impressions
- LinkedIn Org & Brand: clicks, comments, engagement, impressions, likes, shares, unique_impressions, video_views (video only)
- LinkedIn Profile: comments, likes
- YouTube: views, likes, comments
- Pinterest:
- All posts:impressions, pin_clicks, saved, reactions, comments
- Video posts:video_views, video_avg_watch_time, video_10s_views
- Threads: views, likes, replies, reposts, quotes
- Bluesky: likes, replies, reposts
- Mastodon: replies, reblogs, favourites
- Reddit Profile & Subreddit: comments, score
- TikTok: (post metrics not supported)
- Google Business Location: (post metrics not supported)
post_type string
Enum:"image""text""video"
Filter by post type. If omitted, all post types are included.
start
required		 string
The start date
team integer
The team id.

Responses

200

successful operation

404

Resource not found

get/insights/posts/metrics

SocialBu API

https://socialbu.com/api/v1/insights/posts/metrics

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"data": {"property1": [{"date": "2019-08-24",

"value": 0

}

],

"property2": [{"date": "2019-08-24",

"value": 0

}

]

}

}`

tag/Notifications Notifications

Manage your notifications.

tag/Notifications/operation/getNotification Find notification by ID

Returns a notification

Authorizations:

HTTP: bearerAuth

path Parameters
id
required		 integer
ID of notification to return

Responses

200

successful operation

404

Resource not found

get/notifications/{id}

SocialBu API

https://socialbu.com/api/v1/notifications/{id}

Response samples

Content type

application/json

Copy

`{"created_at": "2019-08-24T14:15:22Z",

"id": "string",

"read_at": "2019-08-24T14:15:22Z",

"is_unread": true,

"title": "string",

"body": "string",

"url": "string",

"level": "string"

}`

tag/Notifications/operation/getNotifications Get notifications

Returns a list of notifications

Authorizations:

HTTP: bearerAuth

Responses

200

successful operation

400

Bad Request

404

Resource not found

405

Validation exception

get/notifications

SocialBu API

https://socialbu.com/api/v1/notifications

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"items": [{"created_at": "2019-08-24T14:15:22Z",

"id": "string",

"read_at": "2019-08-24T14:15:22Z",

"is_unread": true,

"title": "string",

"body": "string",

"url": "string",

"level": "string"

}

],

"currentPage": 0,

"lastPage": 0,

"nextPage": 0,

"total": 0

}`

tag/Notifications/operation/getUnreadNotifications Get unread notifications

Returns a list unread notifications

Authorizations:

HTTP: bearerAuth

Responses

200

successful operation

400

Bad Request

404

Resource not found

405

Validation exception

get/notifications/unread

SocialBu API

https://socialbu.com/api/v1/notifications/unread

Response samples

Content type

application/json

Copy Expand all Collapse all

"currentPage": 0,

"lastPage": 0,

"nextPage": 0,

"total": 0

}`

tag/Notifications/operation/markAsRead Mark a notification as read

Authorizations:

HTTP: bearerAuth

path Parameters
id
required		 integer
ID of notifications to mark read

Responses

200

successful operation

404

Resource not found

post/notifications/{id}/mark_read

SocialBu API

https://socialbu.com/api/v1/notifications/{id}/mark\_read

Response samples

Content type

application/json

Copy

`{"created_at": "2019-08-24T14:15:22Z",

"id": "string",

"read_at": "2019-08-24T14:15:22Z",

"is_unread": true,

"title": "string",

"body": "string",

"url": "string",

"level": "string"

}`

tag/Notifications/operation/markAsUnread Mark a notification as unread

Authorizations:

HTTP: bearerAuth

path Parameters
id
required		 integer
ID of notification to mark as unread

Responses

200

successful operation

404

Resource not found

post/notifications/{id}/mark_unread

SocialBu API

https://socialbu.com/api/v1/notifications/{id}/mark\_unread

Response samples

Content type

application/json

Copy

`{"created_at": "2019-08-24T14:15:22Z",

"id": "string",

"read_at": "2019-08-24T14:15:22Z",

"is_unread": true,

"title": "string",

"body": "string",

"url": "string",

"level": "string"

}`

tag/Notifications/operation/markAllAsRead Mark all notifications as read

Authorizations:

HTTP: bearerAuth

Responses

200

successful operation

400

Bad request.

post/notifications/mark_all_read

SocialBu API

https://socialbu.com/api/v1/notifications/mark\_all\_read

tag/Social-Inbox Social Inbox

Access and manage social inbox conversations.

tag/Social-Inbox/operation/getSocialInboxConversation Get inbox conversation

Returns one inbox conversation available to the authenticated user.

Authorizations:

HTTP: bearerAuth

path Parameters
convoId
required		 integer
Conversation ID.
inboxId
required		 string^[at]_\d+$
Inbox identifier, such as a_123 or t_45.

Responses

200

Conversation retrieved successfully.

404

Conversation not found or not available to the authenticated user.

get/inbox/{inboxId}/{convoId}

SocialBu API

https://socialbu.com/api/v1/inbox/{inboxId}/{convoId}

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"id": 0,

"type": "string",

"options": { },

"external_id": "string",

"contact": { },

"latest": { },

"account": { },

"status": "closed",

"content": "string",

"attachments": [{ }

],

"tags": ["string"

],

"created_at": "2019-08-24T14:15:22Z",

"latest_at": "2019-08-24T14:15:22Z",

"assigned_to": { },

"creator_account": { }

}`

tag/Social-Inbox/operation/getSocialInboxConversationItemReplies List conversation item replies

Returns paginated visible replies for a conversation item.

Authorizations:

HTTP: bearerAuth

path Parameters
convoId
required		 integer
Conversation ID.
inboxId
required		 string^[at]_\d+$
Inbox identifier, such as a_123 or t_45.
itemId
required		 integer
Conversation item ID.
query Parameters
page integer >= 1
Default: 1
Page number to return.
per_page integer [ 1 .. 100 ]
Default: 20
Number of replies per page, up to 100.
reverse boolean
Default: false
When true, return newest replies first.

Responses

200

Conversation item replies retrieved successfully.

404

Conversation item not found or not available to the authenticated user.

get/inbox/{inboxId}/{convoId}/items/{itemId}/replies

SocialBu API

https://socialbu.com/api/v1/inbox/{inboxId}/{convoId}/items/{itemId}/replies

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"items": [{"id": 0,

"data": { },

"content": "string",

"contact": { },

"attachments": [{ }

],

"type": "string",

"parent_id": 0,

"options": { },

"status": "string",

"created_at": "2019-08-24T14:15:22Z",

"external_id": "string",

"creator_account": { },

"children_count": 0,

"conversation_id": 0,

"is_internal": true,

"note_author": { },

"tagged_users": [{ }

]

}

],

"currentPage": 0,

"lastPage": 0,

"nextPage": 0,

"total": 0

}`

tag/Social-Inbox/operation/getSocialInboxConversationItems List conversation items

Returns paginated top-level items for an inbox conversation.

Authorizations:

HTTP: bearerAuth

path Parameters
query Parameters
page integer >= 1
Default: 1
Page number to return.
per_page integer [ 1 .. 100 ]
Default: 20
Number of items per page, up to 100.
reverse boolean
Default: false
When true, return newest items first.

Responses

200

Conversation items retrieved successfully.

404

Conversation not found or not available to the authenticated user.

get/inbox/{inboxId}/{convoId}/items

SocialBu API

https://socialbu.com/api/v1/inbox/{inboxId}/{convoId}/items

Response samples

Content type

application/json

Copy Expand all Collapse all

"currentPage": 0,

"lastPage": 0,

"nextPage": 0,

"total": 0

}`

tag/Social-Inbox/operation/getSocialInboxConversations List inbox conversations

Returns paginated conversations for an account or team inbox.

Authorizations:

HTTP: bearerAuth

path Parameters
inboxId
required		 string^[at]_\d+$
Inbox identifier, such as a_123 for an account inbox or t_45 for a team inbox.
query Parameters
account_types[] Array of strings
Filter conversations by one or more connected account types, such as facebook.page, instagram.api, or bluesky.profile.
assigned_to string
Filter by assignment. Use mine, unassigned, assigned, or a user ID.
end string
Include conversations updated on or before this date/time.
item_types Array of strings
Filter conversations containing one or more inbox item types.
page integer >= 1
Default: 1
Page number to return.
per_page integer [ 1 .. 100 ]
Default: 100
Number of conversations per page, up to 100.
post_id string
Filter conversations whose external_id matches this platform post ID.
q string
Search contact name, username, or item content.
start string
Include conversations updated on or after this date/time.
status string
Enum:"closed""open""pending""spam"
Filter conversations by status.
unread boolean
When true, return only conversations containing qualifying unread inbound items.

Responses

200

Conversations retrieved successfully.

404

Inbox not found or not available to the authenticated user.

422

The given data was invalid.

get/inbox/{inboxId}

SocialBu API

https://socialbu.com/api/v1/inbox/{inboxId}

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"items": [{"id": 0,

"type": "string",

"options": { },

"external_id": "string",

"contact": { },

"latest": { },

"account": { },

"status": "closed",

"content": "string",

"attachments": [{ }

],

"tags": ["string"

],

"created_at": "2019-08-24T14:15:22Z",

"latest_at": "2019-08-24T14:15:22Z",

"assigned_to": { },

"creator_account": { }

}

],

"currentPage": 0,

"lastPage": 0,

"nextPage": 0,

"total": 0

}`

tag/Social-Inbox/operation/getSocialInboxes List social inboxes

Returns account and team inboxes available to the authenticated user.

Authorizations:

HTTP: bearerAuth

Responses

200

Inboxes retrieved successfully.

get/inbox

SocialBu API

https://socialbu.com/api/v1/inbox

Response samples

Content type

application/json

Copy Expand all Collapse all

[{"id": "a_123",\ \ "name": "string",\ \ "type": "account",\ \ "image": "string",\ \ "active": true,\ \ "active_conversations": 0,\ \ "accounts": [{ }\ \ ],\ \ "members": [{ }\ \ ],\ \ "email_notifications": true\ \ }\ \ ]

tag/Social-Inbox/operation/performSocialInboxConversationAction Perform a conversation action

Performs a network-supported action on a conversation. Supported actions and payload fields depend on the conversation network and type.

Authorizations:

HTTP: bearerAuth

path Parameters
action
required		 string
Network action to perform. Common examples include message, reply, comment, vote, and react.
convoId
required		 integer
Conversation ID.
inboxId
required		 string^[at]_\d+$
Inbox identifier, such as a_123 or t_45.
Request Body schema: application/json optional
attachments Array of objects
Media attachments for networks/actions that support media responses.
content string
Text for comment/reply/message actions. Some networks also accept text or message.
message string
Alternate message field accepted by some network handlers.
reaction string
Reaction value for react, such as love or an emoji, depending on the network.
text string
Alternate text field accepted by some network handlers.
vote integer
Enum:-101
Vote direction for vote, where supported.
property name*
additional property		 any

Responses

200

Action performed successfully.

400

Invalid conversation or action request.

404

Conversation not found or not available to the authenticated user.

422

The action is not valid for this conversation.

post/inbox/{inboxId}/{convoId}/{action}

SocialBu API

https://socialbu.com/api/v1/inbox/{inboxId}/{convoId}/{action}

Request samples

Content type

application/json

Copy

`{"content": "Thanks for reaching out."

}`

Response samples

Content type

application/json

Copy

{ }

tag/Social-Inbox/operation/performSocialInboxConversationItemAction Perform a conversation item action

Performs a network-supported action on a conversation item. Supported actions and payload fields depend on the item network and type.

Authorizations:

HTTP: bearerAuth

path Parameters
action
required		 string
Network action to perform. Common examples include reply, comment, vote, and react.
convoId
required		 integer
Conversation ID.
inboxId
required		 string^[at]_\d+$
Inbox identifier, such as a_123 or t_45.
itemId
required		 integer
Conversation item ID.
Request Body schema: application/json optional

Responses

200

Action performed successfully.

400

Invalid item or action request.

404

Conversation item not found or not available to the authenticated user.

422

The action is not valid for this item.

post/inbox/{inboxId}/{convoId}/items/{itemId}/{action}

SocialBu API

https://socialbu.com/api/v1/inbox/{inboxId}/{convoId}/items/{itemId}/{action}

Request samples

Content type

application/json

Copy

`{"content": "Thanks for reaching out."

}`

Response samples

Content type

application/json

Copy

{ }

tag/Social-Inbox/operation/updateSocialInboxConversationStatuses Update conversation statuses

Updates the status of one or more inbox conversations after validating all requested conversations.

Authorizations:

HTTP: bearerAuth

path Parameters
inboxId
required		 string^[at]_\d+$
Inbox identifier, such as a_123 or t_45.
Request Body schema: application/json required
conversation_ids
required		 Array of integers
Conversation IDs to update.
status
required		 string
Enum:"closed""open""pending""spam"
New conversation status.

Responses

200

Conversation statuses updated successfully.

404

One or more conversations were not found or not available to the authenticated user.

422

The given data was invalid.

patch/inbox/{inboxId}/status

SocialBu API

https://socialbu.com/api/v1/inbox/{inboxId}/status

Request samples

Content type

application/json

Copy Expand all Collapse all

`{"conversation_ids": [0

],

"status": "closed"

}`

tag/Social-Listening Social Listening

Manage social listening sources, streams, and stream items.

tag/Social-Listening/operation/archiveListeningStreamItem Archive a listening item

Marks one listening item as archived.

Authorizations:

HTTP: bearerAuth

path Parameters
id
required		 integer
Listening stream ID.
itemId
required		 integer
Listening item ID.

Responses

200

Listening item archived successfully.

403

Social listening is not available on the current plan.

404

Stream or item not found.

patch/listen/streams/{id}/items/{itemId}/archive

SocialBu API

https://socialbu.com/api/v1/listen/streams/{id}/items/{itemId}/archive

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"id": 0,

"platform": "bluesky",

"platform_item_id": "string",

"permalink": "http://example.com",

"title": "string",

"body": "string",

"actor": {"id": "string",

"name": "string",

"avatar_url": "http://example.com"

},

"published_at": "2019-08-24T14:15:22Z",

"status": "active",

"matched_query": "string",

"ai_analysis": {"sentiment": "mixed",

"tags": ["string"

],

"analyzed_at": "2019-08-24T14:15:22Z"

},

"created_at": "2019-08-24T14:15:22Z"

}`

tag/Social-Listening/operation/archiveAllListeningStreamItems Archive all active listening items

Archives every active item in a social listening stream.

Authorizations:

HTTP: bearerAuth

path Parameters
id
required		 integer
Listening stream ID.

Responses

200

Listening items archived successfully.

403

Social listening is not available on the current plan.

404

Stream not found or not available to the authenticated user.

patch/listen/streams/{id}/items/archive_all

SocialBu API

https://socialbu.com/api/v1/listen/streams/{id}/items/archive\_all

Response samples

Content type

application/json

Copy

`{"success": true,

"count": 0

}`

tag/Social-Listening/operation/bulkArchiveListeningStreamItems Archive multiple listening items

Archives active items in a social listening stream by item ID.

Authorizations:

HTTP: bearerAuth

path Parameters
id
required		 integer
Listening stream ID.
Request Body schema: application/json required
item_ids
required		 Array of integers non-empty
Listening item IDs to archive or delete.

Responses

200

Listening items archived successfully.

403

Social listening is not available on the current plan.

404

Stream not found or not available to the authenticated user.

422

The given data was invalid.

patch/listen/streams/{id}/items/bulk_archive

SocialBu API

https://socialbu.com/api/v1/listen/streams/{id}/items/bulk\_archive

Request samples

Content type

application/json

Copy Expand all Collapse all

`{"item_ids": [0

]

}`

Response samples

Content type

application/json

Copy

`{"success": true,

"count": 0

}`

tag/Social-Listening/operation/createListeningStream Create a listening stream

Creates a social listening stream for the authenticated user or an allowed team.

Authorizations:

HTTP: bearerAuth

Request Body schema: application/json required
name
required		 string <= 180 characters
query
required		 Array of strings [ 1 .. 10 ] items [ items <= 500 characters ]
sources
required		 Array of strings non-empty
Items Enum:"bluesky""hackernews""reddit""threads""tiktok""twitter""youtube"
description string or null
options object
platform_queries object
team_id integer or null

Responses

201

Listening stream created successfully.

403

Social listening is not available on the current plan, the stream limit is reached, or the team is not allowed.

422

The given data was invalid.

post/listen/streams

SocialBu API

https://socialbu.com/api/v1/listen/streams

Request samples

Content type

application/json

Copy Expand all Collapse all

`{"name": "string",

"query": ["string"

],

"sources": ["bluesky"

]

}`

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"id": 0,

"name": "string",

"description": "string",

"query": ["string"

],

"sources": ["string"

],

"platform_queries": {"property1": ["string"

],

"property2": ["string"

]

},

"is_active": true,

"can_view": true,

"can_manage": true,

"team": {"id": 0,

"name": "string"

},

"notify_daily_digest": true,

"digest_recipient_ids": [0

],

"ai_analysis": { },

"rss_url": "http://example.com",

"embed_url": "http://example.com",

"embed_urls": {"property1": "http://example.com",

"property2": "http://example.com"

},

"last_item_at": "2019-08-24T14:15:22Z",

"total_items_found": 0,

"item_count": 0,

"active_count": 0,

"created_at": "2019-08-24T14:15:22Z"

}`

tag/Social-Listening/operation/deleteListeningStreamItem Delete a listening item

Deletes one saved item from a listening stream. Requires Manage Social Listening permission for team streams.

Authorizations:

HTTP: bearerAuth

path Parameters
id
required		 integer
Listening stream ID.
itemId
required		 integer
Listening item ID.

Responses

200

Listening item deleted successfully.

403

The authenticated user cannot manage this stream.

404

Stream or item not found.

delete/listen/streams/{id}/items/{itemId}

SocialBu API

https://socialbu.com/api/v1/listen/streams/{id}/items/{itemId}

Response samples

Content type

application/json

Copy

`{"success": true

}`

tag/Social-Listening/operation/bulkDeleteListeningStreamItems Delete multiple listening items

Deletes listening items from a stream by item ID. Requires Manage Social Listening permission for team streams.

Authorizations:

HTTP: bearerAuth

path Parameters
id
required		 integer
Listening stream ID.
Request Body schema: application/json required
item_ids
required		 Array of integers non-empty
Listening item IDs to archive or delete.

Responses

200

Listening items deleted successfully.

403

The authenticated user cannot manage this stream or social listening is not available on the current plan.

404

Stream not found or not available to the authenticated user.

422

The given data was invalid.

post/listen/streams/{id}/items/bulk_delete

SocialBu API

https://socialbu.com/api/v1/listen/streams/{id}/items/bulk\_delete

Request samples

Content type

application/json

Copy Expand all Collapse all

`{"item_ids": [0

]

}`

Response samples

Content type

application/json

Copy

`{"success": true,

"count": 0

}`

tag/Social-Listening/operation/getListeningStreamItems Fetch listening stream items

Returns paginated items from a social listening stream available to the authenticated user.

Authorizations:

HTTP: bearerAuth

path Parameters
id
required		 integer
Listening stream ID.
query Parameters
from string
Example: from=2026-05-01
Include items published on or after this date.
page integer >= 1
Default: 1
Page number to return.
per_page integer [ 1 .. 100 ]
Default: 20
Number of items per page, up to 100.
platform string
Enum:"bluesky""hackernews""reddit""threads""tiktok""twitter""youtube"
Filter items by source platform.
search string >= 3 characters
Search title and body text. Must be at least 3 characters.
status string
Enum:"active""archived"
Filter by item status.
to string
Example: to=2026-05-05
Include items published on or before this date.

Responses

200

Listening items retrieved successfully.

404

Stream not found or not available to the authenticated user.

422

The given data was invalid.

get/listen/streams/{id}/items

SocialBu API

https://socialbu.com/api/v1/listen/streams/{id}/items

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"items": [{"id": 0,

"platform": "bluesky",

"platform_item_id": "string",

"permalink": "http://example.com",\
"title": "string",

"body": "string",

"actor": {"id": "string",

"name": "string",

"avatar_url": "http://example.com"\
},

"published_at": "2019-08-24T14:15:22Z",

"status": "active",

"matched_query": "string",

"ai_analysis": {"sentiment": "mixed",

"tags": ["string"

],

"analyzed_at": "2019-08-24T14:15:22Z"

},

"created_at": "2019-08-24T14:15:22Z"

}

],

"currentPage": 0,

"lastPage": 0,

"nextPage": 0,

"total": 0

}`

tag/Social-Listening/operation/getListeningStreamItem Get a listening item

Returns one saved item from a listening stream available to the authenticated user.

Authorizations:

HTTP: bearerAuth

path Parameters
id
required		 integer
Listening stream ID.
itemId
required		 integer
Listening item ID.

Responses

200

Listening item retrieved successfully.

404

Stream or item not found.

get/listen/streams/{id}/items/{itemId}

SocialBu API

https://socialbu.com/api/v1/listen/streams/{id}/items/{itemId}

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"id": 0,

"platform": "bluesky",

"platform_item_id": "string",

"permalink": "http://example.com",

"title": "string",

"body": "string",

"actor": {"id": "string",

"name": "string",

"avatar_url": "http://example.com"

},

"published_at": "2019-08-24T14:15:22Z",

"status": "active",

"matched_query": "string",

"ai_analysis": {"sentiment": "mixed",

"tags": ["string"

],

"analyzed_at": "2019-08-24T14:15:22Z"

},

"created_at": "2019-08-24T14:15:22Z"

}`

tag/Social-Listening/operation/getListeningStream Get a listening stream

Returns a listening stream available to the authenticated user, including query configuration, RSS/embed URLs, counts, and quota state.

Authorizations:

HTTP: bearerAuth

path Parameters
id
required		 integer
Listening stream ID.

Responses

200

Listening stream retrieved successfully.

403

Social listening is not available on the current plan.

404

Stream not found or not available to the authenticated user.

get/listen/streams/{id}

SocialBu API

https://socialbu.com/api/v1/listen/streams/{id}

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"id": 0,

"name": "string",

"description": "string",

"query": ["string"

],

"sources": ["string"

],

"platform_queries": {"property1": ["string"

],

"property2": ["string"

]

},

"is_active": true,

"can_view": true,

"can_manage": true,

"team": {"id": 0,

"name": "string"

},

"notify_daily_digest": true,

"digest_recipient_ids": [0

],

"ai_analysis": { },

"rss_url": "http://example.com",

"embed_url": "http://example.com",

"embed_urls": {"property1": "http://example.com",

"property2": "http://example.com"

},

"last_item_at": "2019-08-24T14:15:22Z",

"total_items_found": 0,

"item_count": 0,

"active_count": 0,

"created_at": "2019-08-24T14:15:22Z"

}`

tag/Social-Listening/operation/getListeningSources List listening sources

Returns the source platforms available for social listening streams.

Authorizations:

HTTP: bearerAuth

Responses

200

Listening sources retrieved successfully.

get/listen/sources

SocialBu API

https://socialbu.com/api/v1/listen/sources

Response samples

Content type

application/json

Copy Expand all Collapse all

[{"key": "string",\ \ "label": "string",\ \ "color": "string"\ \ }\ \ ]

tag/Social-Listening/operation/getListeningStreams List listening streams

Returns paginated listening streams available to the authenticated user, including team visibility and quota state.

Authorizations:

HTTP: bearerAuth

query Parameters
page integer >= 1
Default: 1
Page number to return.
per_page integer [ 1 .. 100 ]
Default: 20
Number of streams per page, up to 100.

Responses

200

Listening streams retrieved successfully.

422

The given data was invalid.

get/listen/streams

SocialBu API

https://socialbu.com/api/v1/listen/streams

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"items": [{"id": 0,

"name": "string",

"description": "string",

"query": ["string"

],

"sources": ["string"

],

"platform_queries": {"property1": ["string"

],

"property2": ["string"

]

},

"is_active": true,

"can_view": true,

"can_manage": true,

"team": {"id": 0,

"name": "string"

},

"notify_daily_digest": true,

"digest_recipient_ids": [0

],

"ai_analysis": { },

"rss_url": "http://example.com",\
"embed_url": "http://example.com",\
"embed_urls": {"property1": "http://example.com",\
"property2": "http://example.com"\
},

"last_item_at": "2019-08-24T14:15:22Z",

"total_items_found": 0,

"item_count": 0,

"active_count": 0,

"created_at": "2019-08-24T14:15:22Z"

}

],

"currentPage": 0,

"lastPage": 0,

"nextPage": 0,

"total": 0,

"monthly_item_quota": { }

}`

tag/Social-Listening/operation/unarchiveListeningStreamItem Unarchive a listening item

Marks one listening item as active.

Authorizations:

HTTP: bearerAuth

path Parameters
id
required		 integer
Listening stream ID.
itemId
required		 integer
Listening item ID.

Responses

200

Listening item unarchived successfully.

403

Social listening is not available on the current plan.

404

Stream or item not found.

patch/listen/streams/{id}/items/{itemId}/unarchive

SocialBu API

https://socialbu.com/api/v1/listen/streams/{id}/items/{itemId}/unarchive

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"id": 0,

"platform": "bluesky",

"platform_item_id": "string",

"permalink": "http://example.com",

"title": "string",

"body": "string",

"actor": {"id": "string",

"name": "string",

"avatar_url": "http://example.com"

},

"published_at": "2019-08-24T14:15:22Z",

"status": "active",

"matched_query": "string",

"ai_analysis": {"sentiment": "mixed",

"tags": ["string"

],

"analyzed_at": "2019-08-24T14:15:22Z"

},

"created_at": "2019-08-24T14:15:22Z"

}`

tag/AI-Tools AI Tools

tag/AI-Tools/operation/listAiTools List available AI tools

Returns a list of all available AI tools with their field definitions.

Authorizations:

HTTP: bearerAuth

Responses

200

List of AI tools

get/ai/tools

SocialBu API

https://socialbu.com/api/v1/ai/tools

Response samples

Content type

application/json

Copy Expand all Collapse all

`{"tools": [{"slug": "tweet_generator",

"name": "Tweet Generator",

"fields": [{ }

]

}

]

}`

tag/AI-Tools/operation/runAiTool Run an AI tool

Executes an AI tool by its slug and returns the generated content.

Authorizations:

HTTP: bearerAuth

path Parameters
slug
required		 string
The slug of the AI tool to run (e.g., tweet_generator).
Request Body schema: application/json
team_id integer or null
Team ID (optional). If provided, content is generated under the team.

Responses

200

AI tool executed successfully. Returns the generated content.

400

Invalid tool slug or bad request parameters.

403

AI credit limit reached or insufficient permissions.

422

Validation error - required fields missing or invalid.

429

Rate limit exceeded.

post/ai/tools/{slug}

SocialBu API

https://socialbu.com/api/v1/ai/tools/{slug}

Request samples

Content type

application/json

Copy

{ }

Response samples

Content type

application/json

Copy

`{"credit_cost": 0

}`