Tool reference - PublishBuddy

Every tool runs with the permissions of the user behind the token, inside the request’s workspace. Profile-scoped tools take profile UUIDs; call list_profiles first to get them. Dates are ISO 8601 and UTC unless the tool says otherwise. Credits are only charged for tools that call an AI model. See Credits.

Profiles and preferences

Tool	What it does	Credits
`list_profiles`	Lists every social profile connected to the workspace: name, network, avatar, connection status, and UUID. Start here.	0
`get_user_preferences`	Returns your saved content preferences: tone, content themes, hashtag count, emoji level, call-to-action style, preferred platforms. Assistants read this before drafting.	0
`save_user_preferences`	Saves or updates those preferences. All fields optional; only the ones you pass change.	0

Posts

Tool	What it does	Credits
`create_post`	Creates a draft for one profile: caption (optional when media is attached), post type, media from the library by UUID, and labels. Returns the post, including its ID. Nothing is published until you schedule or queue it.	0
`update_post`	Changes a post’s caption, media, or labels. Only while the post is a draft or waiting to publish.	0
`delete_post`	Deletes a draft or waiting post. Irreversible.	0
`get_draft_posts`	Lists drafts for the given profiles, optionally filtered by last-updated date range. Default 20.	0
`get_scheduled_posts`	Lists posts waiting to publish for the given profiles, with content, scheduled time, and status. Optional date range. Default 20.	0

Scheduling

Tool	What it does	Credits
`schedule_post`	Schedules a draft for a specific date and time (ISO 8601) on a profile.	0
`add_post_to_queue`	Adds a draft to a profile’s posting queue at the top or bottom; the next free timeslot publishes it. The profile needs a queue configured in the dashboard.	0

Analytics

Tool	What it does	Credits
`get_engagement_summary`	Published posts, likes, reach, engagements, graphs, and best time to post for one profile (with previous-period comparison) or the whole workspace. Takes a preset timeframe (`last_7_days` through `for_all_time`) or a custom date range.	0
`get_top_posts`	Posts ranked by a metric for the given profiles. `sort_direction: desc` for best, `asc` for worst. 1 to 20 posts, optional date range.	1
`get_best_posting_times`	Ranked days and hours with expected engagement, from the profiles’ own history. Defaults to the last 30 days.	0
`get_hashtag_performance`	Top hashtags by engagement and reach for a profile over a date range. Up to 50.	0

AI images

Image generation runs in the background. generate_image and edit_image return a job ID immediately; poll check_image_generation_status until it reports the finished image, which is saved to the media library and can be attached to a post by UUID.

Tool	What it does	Credits
`generate_image`	Generates an image from a prompt, with optional style, aspect ratio (square by default), and target platform. Takes roughly 15 to 30 seconds.	17
`edit_image`	Edits an existing image with a prompt: either the output of a previous generation or edit job, or an image already in the media library.	17
`check_image_generation_status`	Returns the job’s status and, when complete, the image URL.	0

Visual insights

These tools work on posts that have already been published and analysed. They are useful for answering “why did this work?” and for turning what worked into a brief for the next post.

Tool	What it does	Credits
`analyze_post_visuals`	Structured visual features for one published post: palette, detected objects, text overlays, transcript phrases. `lite` reads the cached extraction; `quick` and `deep` re-analyse with a larger model and consume a daily drill-down quota.	0
`analyze_post_drivers`	Explains why a post performed by comparing its visual features against the profile’s last 90 days of posts.	0
`search_library`	Searches published posts by visual features: colors, objects, on-screen text, or spoken phrases. Up to 50 results.	0
`build_creative_brief`	Intersects the visual features of several reference posts into a brief, a rendered prompt, and ready-to-use arguments for `generate_image`.	0
`reextract_visuals`	Re-runs feature extraction for up to 50 posts when a search returns too few matches or an extraction looks wrong.	0

Confirmation and safety

The server does not pause for confirmation itself; that is your client’s job, and every major client asks before running a tool unless you have allowed it. Two properties make the write tools safe to allow:

create_post only ever creates a draft. Publishing requires a second, explicit call to schedule_post or add_post_to_queue.
delete_post refuses anything that is publishing or already published.

Revoke the token from User Settings → Login & Security at any time to cut off every client using it.

​Profiles and preferences

​Posts

​Scheduling

​Analytics

​AI images

​Visual insights

​Confirmation and safety