posterly

Ask posterly Support AI an authenticated question using posterly docs plus read-only account/post diagnostics for the caller workspace. Requires API auth and accounts:read + posts:read scopes. Human tickets are never opened on the first answer; ticket creation requires a follow-up in a continued conversation with an assistant answer plus request_human=true and confirm_escalation=true after explicit user confirmation.

Run a live local-profile audit for a connected Google Business Profile location. Returns the 0-100 completeness score, letter grade, a score for each section (profile basics, hours, categories, description, photos, attributes, review health), and recommendations.

Cancel the authenticated user's posterly subscription. DESTRUCTIVE billing action; requires the billing:write scope. ALWAYS ask the user why they are cancelling FIRST and pass their answer as reason (one of the allowed values). By default an active or trialing plan is set to cancel at the end of the current period. A past_due or unpaid plan always ends now, even when immediate is false: the unpaid renewal is dropped and payment retries stop. Pass immediate=true only when the user explicitly wants an active plan cancelled right now. Only call after the user explicitly confirms.

Connect a credential-based social account (telegram, bluesky, discord, wordpress, devto, hashnode, lemmy) directly, without a browser session. Call list_platforms with view=connect_link first to discover the exact credential fields the platform needs. Prefer scoped secrets: app passwords (Bluesky, WordPress), bot tokens (Telegram), webhook URLs (Discord), and API tokens (Dev.to, Hashnode) over primary passwords. Warn the user that any credential they share passes through this conversation. For OAuth platforms (Instagram, X, LinkedIn, ...) use create_connect_session instead.

Create a new posterly API key for the authenticated user. SECRET-CREATING WRITE: only use after explicit user confirmation. The new key can only request scopes already present on the calling dashboard-created API key; OAuth and managed assistant tokens cannot mint keys. Team management (members:read, members:write) and client portal sign-in link permissions are never copied or granted here: a person turns them on in /dashboard/api.

Create a short-lived dashboard handoff session for connecting a social account. Open connect_session.connect_url for the user, then poll list_accounts with view=connect_session so you can narrate progress.

Create a human drop page so ChatGPT or Claude users can upload a laptop file without dashboard login. Returns drop_url (https://www.poster.ly/drop/). Send that URL to the user, wait, then call list_media. This is not the chat paperclip and not create_signed_upload.

Schedule or immediately publish one social media post. DESTRUCTIVE WRITE that creates content on the user's connected social account. Always confirm caption + scheduled_at + account_id/workspace with the user before calling. For Instagram, distinguish caption @mentions from native instagram_settings.user_tags and co-author instagram_settings.collaborators; call list_platforms with view=schema and account_id before either native feature. Native media tags work with eligible direct or Meta-linked accounts; collaborators require an eligible Meta-linked account. Instagram caption add-ons (caption_addon poll or comment prompt) need a Facebook Login account, a caption, and a feed photo, Reel, or carousel. Stories are rejected, and a poll cannot be combined with a comment prompt. Third-party media URLs are copied into posterly storage before the post is saved; short-lived signed URLs must still be live when this tool runs. For multiple posts, prefer create_posts_batch after confirming every item.

Create 1-25 scheduled or immediate social posts in one API request. DESTRUCTIVE WRITE: show the user every post's account/platform, caption or thread text, scheduled time, media, settings, and workspace, then get explicit confirmation for the whole batch before calling. Third-party media URLs are copied into posterly storage before each post is saved. Partial success is possible; failed items return their array index.

Create a signed upload URL for a larger image or video. PUT the raw bytes to the returned upload_url (object storage) with the returned headers, then pass public_url to create_post.

Create a webhook subscription for post/account/analytics events. WRITE WITH OUTBOUND SIDE EFFECTS: show the user the target URL, workspace, events, and active state, then get explicit confirmation before calling. The response includes the signing secret once.

Revoke a posterly API key owned by the authenticated user. DESTRUCTIVE: show the user the exact key ID/prefix/name if available and get explicit confirmation before calling. Cannot revoke the key currently authenticating this request, OAuth-issued keys, or managed assistant keys.

Delete posts. DESTRUCTIVE and IRREVERSIBLE. post_id: delete one post; fetch it with get_post first, confirm what will be deleted, then pass confirm=true. A post that is currently publishing is never deleted. A published post is taken down only when the user also explicitly confirms the live removal and you pass confirm_published=true. Choose delete_mode=posterly to remove only the posterly record and leave the live post up, or delete_mode=platform with confirm_published=true to take down the live post too. Live deletion supports eligible connected platforms with saved post IDs and deletion permissions; refusals keep the record. Threads requires threads_delete. YouTube requires youtube.force-ssl or equivalent, upload alone is insufficient. A published post with no live URL and no platform id is removed from posterly only. group_id: delete every draft, scheduled, failed, or paused post matching a caller-defined group_id, post_group_id, api_group_id, or release_id. A group delete never removes published posts. Preview then confirm: call without confirm to get a preview and preview_id, show it, then call again with confirm=true and that preview_id.

Disconnect a connected social account from posterly. DESTRUCTIVE and IRREVERSIBLE: this removes the account connection, emits account.disconnected webhooks, and may transfer Instagram scheduled posts to a replacement account. Always call list_accounts first, show the user the exact account/platform/workspace, and get explicit confirmation before calling.

Dismiss a proactive post suggestion so it stops appearing. WRITE: confirm the exact suggestion with the user first. Never dismisses a suggestion that was already turned into a scheduled post.

Downgrade the authenticated user's posterly subscription one tier (or to an explicit lower tier) at the next renewal with no proration. Billing action; requires the billing:write scope. Only call after the user explicitly confirms.

Find available time slots for posting. Respects a 1-hour gap between posts and preferred hours. Always pass timezone explicitly (default is America/New_York). strategy "best_engagement" (needs account_ids) ranks the next 7 days by when these accounts get the most engagement, with a 1-5 star rating and a reason per slot.

Generate or adapt AI caption suggestions for one or more social platforms. Uses AI Caption Assist quota and returns options only; it does not create, draft, schedule, or publish posts.

Queue an AI image job via posterly using Nano Banana (Gemini) or Grok Imagine Image 2.0 (xAI). Returns job_id. Poll list_jobs with type=image for urls. Thinking high does not change the credit price. COSTS CREDITS - confirm subject + style + aspect_ratio + quality + provider with the user before calling.

Queue an AI video job with Google Veo 3.1 or xAI Grok Imagine Video 1.5. COSTS CREDITS - confirm provider, prompt, duration, resolution, aspect ratio, audio choice, and credit cost with the user before calling. Poll list_jobs with type=video for status and final video_url.

Get the authenticated user's posterly AI credit balance: what is available to spend now, how much of the monthly included allowance is left, purchased pack balance, plan tier, and when the included pool next resets. Credits are a shared WORKSPACE wallet, so this reports the balance the caller can actually spend, not a personal figure. Read-only, spends nothing. Requires the billing:read scope.

One post by ID. view=post (default): caption, status, scheduled time, media, and platform info. view=missing: whether the post is missing required content, media, account, platform settings, or metadata before it can publish; use it to repair failed or imported posts.

Get the authenticated user's posterly subscription: status, tier, cancel-at-period-end, current period end, trial end, and pause state. Read-only. Requires the billing:read scope.

Get the latest posterly product updates and news from the updates feed: new features, improvements, and fixes, newest first. The output says whether more updates exist; page with offset or narrow with since. Requires an active posterly subscription.

List read-only Google Veo and xAI Grok video generation options, input modes, durations, resolutions, aspect ratios, and credit-cost estimates. Does not generate video or spend credits.

Get managed X posting quota, usage, remaining posts, URL-blocking status, and add-on plan info for a workspace.

Connected social accounts and what posterly has learned about them. view=accounts (default): connected accounts, optionally one workspace_id or one account_id; Instagram rows show direct-login vs Meta-linked and whether native media tags/collaborators are available, so check this before Instagram user_tags or collaborators. view=learned_voice (account_id): the voice learned from the account's real published captions (summary, traits, style guidelines, habits); read-only, never overwrites the brand profile. view=performance_profile (account_id): 90-day coaching stats, engagement-rate trend, and summary, or null with a reason (Pro plan or higher). view=connect_session (session_id): poll a session from create_connect_session and narrate status_message; stop at connected, failed, cancelled, or expired.

List recent activity and publish events for posts, including status changes, publish attempts, failures, and retries, newest first. Use this as the agent notifications feed. The output says whether more events exist; page with offset (offset + limit up to 1000) or narrow with since or post_id before concluding nothing else happened.

Analytics for connected accounts (Instagram, X, Facebook Pages, LinkedIn, Google Business Profile, Pinterest, YouTube, and Threads). view=accounts (account_id): daily snapshots and a period summary with platform-native display_metrics labels. Google Business Profile account analytics includes Calls, Website clicks, and Directions along with Profile Views, Search Views, Maps Views, Customer Actions, and Posts. view=posts (account_id): per-post likes, comments/replies, reach, impressions/views, saves, shares, reposts, quotes, and plays, most recent first, with limit/offset. view=insights: per-post feedback insights with a performance tier, diagnosis, next action, and baseline, filtered by account_id, post_id, or checkpoint (1h, 6h, 24h, 72h, 7d); Pro plan or higher. presentation (accounts and posts): compact for Telegram/mobile, table for Markdown clients, json for custom chart/card renderers.

Brands (clients) and their saved context. view=brands (default): brands the caller can access with brand ID, name, workspace ID, source, and account count (optional workspace_id). view=brand (brand_id): one brand with its workspace, source, and linked legacy brand group. view=accounts (brand_id): the social accounts assigned to the brand; use it when the user names a brand rather than an account handle. view=profile (brand_id): voice and tone, audience, keywords, dos and don’ts, visual notes, and other saved brand context.

Social inbox comments and replies for Instagram, Facebook Pages, Threads, and LinkedIn Pages (Pro plan or higher plus posts:read). Without comment_id: list comments filtered by account, platform, unread/flagged, or search, with limit/offset paging. With comment_id: one comment and its replies; only workspace_id may be added.

Social inbox DM conversations for Instagram and Facebook Page inboxes (Threads has no DMs; Pro plan or higher plus posts:read). Without conversation_id: list conversations filtered by account, platform, unread/starred/archived, or search, with limit/offset paging. With conversation_id: one conversation and its messages; there limit is the number of messages (default 50, max 100) and only workspace_id may be added.

List the photos and videos on a Google Business Profile gallery (the media shown on Maps and Search) for one location/account or every accessible GBP location. This is separate from media attached to a post. Returns each item's resource name, category, format, and attribution.

Google Business Profile reviews. view=reviews (default): reviews for one location/account or every accessible location, paging through everything Google has (not just the first 50) with the full untruncated review text, its date, and each location's total review count; filter by rating or unanswered, page with limit/offset. view=review_link (account_id or location_id): the direct public Google review link plus the Google Place ID (ChIJ...); that Place ID is output only and must NOT be passed back as location_id.

AI generation jobs. type=image: one image job by job_id, or recent image jobs when job_id is omitted (filter by status, limit); poll it after generate_image for the finished urls. type=video: one video job by job_id, or recent video jobs (status includes dismissed, limit); poll it after generate_video for the finished video_url.

List the newest media assets for the authenticated user. After create_media_drop, pass drop_session_id to see files uploaded on /drop/. Use public_url with validate_post / create_post. The output says whether every matching file is shown; page with offset (offset + limit up to 1000) when it is not.

List self-serve OAuth developer clients owned by the user. These are public PKCE clients for third-party app integrations.

Platforms, settings schemas, and connection links. view=platforms (default): every posterly integration with posting capabilities, content and media limits, settings schemas, helper tools, and analytics support. view=schema: the settings schema for one connected account_id (preferred: returns account context and connection-specific capabilities, needed before Instagram native tags/collaborators) or one platform; account_id wins if both are given. view=connect_link: dashboard connection links and readiness for every target, or one target (instagram, meta, linkedin_page, twitter, telegram, reddit, wordpress, ...); credential platforms show the credential_fields that connect_account needs. For a guided flow with pollable status, use create_connect_session.

Posts in your workspaces, teammates' too, per your role there (brand-locked seats only see their assigned brands). If workspace_id is omitted, this searches every workspace you belong to. view=list (default): posts filtered by status (scheduled, published, failed, draft), platform, account_id, workspace_id, brand_id, approval_status, approval_waiting_on, and a scheduled date range: scheduled_from (inclusive) and scheduled_to (a plain date includes that whole day), read in timezone (IANA, default UTC; also the zone times are shown in). Returns limit posts (default 20, max 200) starting at offset; with a date range the order defaults to oldest first (order=asc|desc). The output always says whether every matching post was shown. If it says more are available, call again with the offset it gives and keep paging until all are shown before drawing any conclusion about totals, gaps, or how busy a client is. view=counts (scheduled_from and scheduled_to required, up to 366 days): exact totals per day, status, account, and brand for the same filters (limit, offset, and order are ignored); use it for "how many" or "is this month full" questions. approval_waiting_on=client is the same queue as approval_status=pending_client. Each post includes approval.pending_client_approval.

List proactive post suggestions: evidence-based weekly drafts posterly writes in each account's learned voice, each with a rationale tying it back to what has performed well. Filter by account_id and status (pending, scheduled, dismissed; default pending). The output says whether every matching suggestion is shown; page with offset until it does. Read-only; requires a Pro plan or higher. Use dismiss_suggestion to hide one.

Is publishing paused? Shows whether the workspace is paused, which brands are paused (only brands you can see), and whether you may pause, resume, or publish missed posts. Read-only. Change it with manage_publishing_pause.

List API webhook subscriptions, their event filters, active state, and most recent delivery status.

List the people in a workspace: members (with role, status, brand access and API access) and pending invites, plus seats in use. API access says whether a teammate can use this workspace's API plan from their own keys and AI apps; owners and admins also see each member's key count, connected AI apps and last use. Works with an API key that has the Manage team permission (any workspace member can list; brand-limited teammates only see brand ids they can access), or from ChatGPT, Claude and other OAuth connections when the user is an owner or admin of the workspace.

Act on an inbox comment (Pro plan or higher plus posts:write). action=reply (comment_id, content): reply to an Instagram, Facebook Page, Threads, or LinkedIn Page comment; type private is Instagram only, the others are public replies only. action=update (comment_id, is_hidden and/or is_read): hide or unhide it on the platform, or mark it read or unread; reversible, no confirm needed. action=delete (comment_id): delete an Instagram or Facebook Page comment, irreversible and admin only; Threads replies cannot be deleted, hide them instead. reply and delete use preview then confirm: call without confirm to get a preview and preview_id, show it, then call again with confirm=true and that preview_id.

Act on the social inbox (Pro plan or higher plus posts:write). action=send (conversation_id, content): send a DM reply in an Instagram or Facebook Page conversation, honoring the 24-hour messaging window (Threads has no DMs); preview then confirm: call without confirm to get a preview and preview_id, show it, then call again with confirm=true and that preview_id. action=sync (account_id): pull the latest Instagram, Facebook Page, Threads, or LinkedIn inbox data for one account; 30-second cooldown (60 for LinkedIn); Threads and LinkedIn sync comments only.

Change a Google Business Profile gallery (the photos and videos shown on Maps and Search). action=add (source_url, category): add a photo or video from a public https URL (upload it with upload_media first); COVER and PROFILE are single-slot and replace the existing one. action=delete (media_name from list_google_business_media): permanently remove an item from the public profile. Both use preview then confirm: call without confirm to get a preview and preview_id, show it, then call again with confirm=true and that preview_id.

Act on Google Business Profile reviews. action=suggest_reply (star_rating, optional review_text): short, brand-aware AI reply suggestions; uses the AI Caption Assist allowance and never posts. action=reply (review_name, comment): post or update the owner reply. action=delete_reply (review_name): delete the owner reply. reply and delete_reply use preview then confirm: call without confirm to get a preview and preview_id (it repeats the review name, location, and exact reply text; show the reviewer, rating, and review text from list_google_business_reviews alongside it), then call again with confirm=true and that preview_id.

Manage self-serve OAuth 2.1 + PKCE developer clients (public clients with no client secret; list them with list_oauth_clients). action=create: client_name, allowed_redirect_uris, and default_scopes; confirm=true only after the user confirms the name, redirect URIs, and scopes. action=update: client_id plus the changed fields; confirm=true after the user confirms the changes. action=delete: client_id; prevents new authorizations (existing access tokens stay revocable as API keys); preview then confirm: call without confirm to get a preview and preview_id, show it, then call again with confirm=true and that preview_id.

Pause or resume publishing for a whole workspace or one brand (check it first with list_publishing_pauses). Only act when the user asks; never pause on your own initiative. action=pause (optional brand_id; leave it out for the whole workspace): holds every scheduled post in that scope and blocks Post now until an admin resumes. Call it first without confirm to get a preview (scope and how many scheduled posts it holds), show it to the user, and only after they agree call again with confirm=true. Publisher or higher; a seat limited to some brands can only pause those brands. action=resume (optional brand_id; admin or higher): future posts are scheduled again; posts whose time passed while paused stay paused and are listed as missed. Missed posts never publish on their own. action=publish_missed (post_ids from the resume, confirm=true after the user agrees; admin or higher): publishes those missed posts now.

Change a webhook subscription (list them first with list_webhooks). action=update (webhook_id): change URL, events, workspace, description, or active state; outbound side effects, so pass confirm=true only after explicit confirmation. action=delete (webhook_id): remove the subscription; preview then confirm: call without confirm to get a preview and preview_id, show the URL, events, and workspace, then call again with confirm=true and that preview_id. action=test (webhook_id): send a signed webhook.test delivery; confirm=true after explicit confirmation.

Invite, update, or remove a workspace colleague. This SENDS EMAILS and CHANGES WHO CAN ACCESS the workspace. Works with an API key that has the Manage team permission, or from ChatGPT, Claude and other OAuth connections; either way the user must be a workspace owner or admin. ALWAYS preview first: call without confirm, show the returned preview summary to the user, and only call again with confirm: true plus the returned preview_id after the user explicitly approves. action=invite: email and role required (publisher, editor or viewer), optional brand_ids and resend; always sends a pending invite email, never adds anyone instantly. action=update: member_id or invite_id (from list_workspace_members) plus role and/or brand_ids; or member_id plus api_access (true or false, on its own) to turn API and AI app access on or off for that teammate, which lets them use the workspace API plan from their own keys and AI apps (off by default; you cannot change your own; only the owner can change it for an admin; turning it off stops their keys, AI app connections and webhooks for this workspace). action=remove: member_id (removes the teammate and revokes their API keys for this workspace) or invite_id (cancels a pending invite). Admin seats can only be granted in the posterly dashboard. The workspace owner is emailed about every change.

Pause the authenticated user's posterly subscription for 30 days (one pause allowed per 90-day cooldown). Billing action; requires the billing:write scope. Only call after the user explicitly confirms.

Resume the authenticated user's paused posterly subscription, restoring active billing. Requires the billing:write scope.

Run a read-only Google Veo or xAI Grok video helper function before generation. Does not generate video or spend credits.

Submit bounded private operational telemetry after a concrete posterly workflow outcome. This is non-destructive to product content but writes a private feedback event. Never include API keys, prompts, captions, media URLs, personal data, or fabricated outcomes. Requires an authenticated bearer API key and paid API add-on.

File a product bug, idea, or general feedback on the public posterly feedback board (same board users see in the dashboard). Only call this when the human explicitly asks to report a bug, suggest a feature, or send feedback to posterly. Require confirm=true after they approve the title and category. Never use this for tool failures or retries - use submit_agent_feedback for private operational telemetry. Never include API keys, secrets, captions, media URLs, or personal data about third parties. Requires an authenticated bearer API key and paid API add-on.

Run a platform helper for account-specific discovery, such as pinterest.boards, tiktok.creator_info, linkedin.recent_mentions, or x.quota.

Change a scheduled or draft post. DESTRUCTIVE WRITE: show the user a side-by-side of CURRENT vs PROPOSED and pass confirm=true only after explicit confirmation. Edit (default): caption, media, schedule, post_type, or settings; cannot edit published posts; if a client already approved the post, a caption edit reopens caption approval, a media or thumbnail edit reopens asset approval, and a reschedule, account change or settings change reopens both. status (scheduled, paused, or draft, with scheduled_at when scheduling a draft): pause, resume, or move back to draft; send it on its own. release_id (with optional group_id): set or repair external release/group IDs; send it on its own. approval_action (request, approve, request_changes, or reject): change client approval. Only a workspace owner or admin may do this. The actor is the API key user, never a brand guest. request emails the brand reviewers. approve, request_changes, and reject are team-side decisions. request_changes needs approval_note. Optional approval_axis is asset or caption; omit it for both. Send approval_action on its own, and pass confirm=true only after the user explicitly confirms.

Upload an image or video to posterly storage and get a URL for create_post; nothing is published. base64_data with filename: a small file, keep decoded files <=5MB on this relay path. url: fetch a public HTTPS image or video (localhost and private network targets are blocked). For larger files, use create_signed_upload and PUT the raw bytes to its upload_url. Supports JPEG, PNG, GIF, WebP, MP4, MOV, WebM, and counts against the user's storage quota.

Validate and normalize one post without creating it. This is non-destructive: it does not create records, copy remote media, consume post-item/storage quota, reserve X quota, emit webhooks, or enqueue publication. Third-party media may return remote_media_not_materialized because live create performs storage copy and final byte validation. Use this before showing the final preview and asking for confirmation to call create_post.

Who you are and how posterly is connected. view=identity (default): the authenticated user, API key scopes, workspaces, and onboarding next step. Call this first; if onboarding.completed is false, walk About you, Connect, Brand voice, and First post IN THIS conversation and do not send the user to /onboarding-v2. view=status: hosted MCP server version, latest npm version for local app clients, endpoint and API auth health, and update guidance.