Beevi

Create, update, delete a collection item, or add/remove/edit a gallery image (UUID/URL/@mention refs; get_upload_token for local file). 'create': collection_id+name+≥1 image. SHEET (is_primary+label, max 8): 2+ images BLOCK-build (credit); 1 image+generate_reference_sheet:true builds (credit), else free. GALLERY: bundle (caption, max 20); metadata per schema. 'update'/'delete': item_id, replace-not-merge (SHEET regenerates; gallery untouched). GALLERY add/remove/update_image: item_id+image|image_id; caption/visual_description editable. Paste 'mention' verbatim — never edit the UUID. Free-text 'tags' (≤10×40 chars, unique) — prefer per-type (character: Founder, Employee, Customer, Mascot, Model; product: Best seller, New, Seasonal, Signature; location: My business, Event venue, Neighborhood; property: For sale, For rent, Sold) else custom. 'My business' = the business's own premises.

manage_collection_item

Permanently delete a brain memory from the workspace. This cannot be undone. Any existing @mentions of this memory in posts or campaigns will no longer resolve.

delete_memory

A post is a group of platform-specific social posts (e.g., one for LinkedIn, one for Instagram). Delete a social post, removing that platform from the post. The post idea's platforms list is automatically updated. Cannot delete published posts (the content is already live on the platform). Cannot delete the last social post on a post idea — use update_social_post to modify it instead. Use get_post first to see all social posts and their IDs.

delete_social_post

PERMANENTLY delete an entire post — the post idea and all its platform-specific social posts. Always confirm with the user before calling this. Refused if any of its social posts is already published (the live content can't be unpublished by deleting the record). To remove just one platform from a post, use delete_social_post instead. If the post belongs to a campaign, it simply disappears from that campaign's plan.

delete_post

Change ONE slide of an existing carousel and re-render it. Consumes credits (one image edit). To change several slides, call this once per slide in the same turn — the calls run in parallel. Call get_carousel first if you need to know what each slide currently says. Pass `instruction` to adjust the look ("make it darker", "drop the icons"), `text` to change the words, or both. Note that a slide's words are part of its image, so changing them re-renders the slide — the new image keeps the same composition but is not pixel-identical. @mentions in `instruction` attach the real reference, so tag rather than describe: - @[Name](item_image:UUID) — ONE real photo. This is how you honour "use our actual photo of the entrance": call get_collection_item for a ready-to-paste mention per photo. - @[Name](item:UUID) — a sheet item (product / character). A whole GALLERY item is NOT usable here: it would attach every photo it has to this one slide. Name one photo instead. - @[AssetName](asset:UUID) from list_assets, plus @StyleName and @BrandLogo. These share the image model's reference budget with whatever the slide already features, so tag the few that matter. Runs synchronously: when it returns, the slide is already updated. No job to poll.

edit_carousel_slide

Generate a STANDALONE carousel (no post). This tool INVENTS pictures (redrawn, never posted as-is). For the user's own photos untouched, use set_post_photos instead. Prefer generate_post post_type:'carousel' for most requests (one call, attached) — this leaves it unattached (attach_carousel later). Call with `prompt` alone (AI plans every slide) or `prompt`+`slides` (you author them). See those fields for @mentions — a GALLERY item goes only in `prompt`, never `slides[]`. Consumes credits. Returns a job_id; result_metadata has { carousel_id, carousel_folder_id, redirectUrl }.

generate_carousel

Generate or edit images using AI. Text-to-image (no reference_images): up to 4 images from a prompt, brand profile auto-injected by default. Image-to-image (reference_images given): edits/remixes them per the prompt, returns 1 image, brand injection defaults OFF. @mentions in prompt also attach as visual references — see prompt's own description. A mention is usually enough; use reference_images when a role must be unambiguous (e.g. 'image to edit') — mix both if needed. For post-specific covers use generate_cover_image instead. Credits depend on model, resolution, and image count.

generate_image

Generate a cover image for a social media post using AI. Automatically injects the workspace's brand profile and post content for on-brand results. For standalone images without post context, use generate_image instead. @mention support — include these in the prompt to enrich the image: - @BrandLogo — embeds the workspace's brand logo as a visual reference so the AI reproduces it in the image. - @StyleName — applies a saved visual style (e.g. @Watercolor). Call list_styles first to see available styles and their mention syntax. - @[Name](item:UUID) — a generic collection item (product / property / location / character / clothing / screenshot / custom). Sheet items attach a composed reference sheet; gallery items (property, location, screenshot) spread into all their photos. Call list_collection_items first to discover available items and their mention syntax. - @[Name](item_image:UUID) — ONE specific photo from a gallery item (not the whole set). Call get_collection_item to get a ready-to-paste item_image mention for each image. - @[Name](asset:UUID) — any image from Brand Media as a visual reference. list_assets returns a ready-to-paste mention for every image; paste it verbatim. Consumes credits based on model and resolution. Returns the generated asset's ID, URL, and filename for immediate use in update_post.

generate_cover_image

Generate a new post using AI. A post groups platform-specific social posts (e.g. LinkedIn + Instagram); AI writes each from your prompt, brand profile, and @mentions. For pre-written content, use create_post. Cover: cover_media (asset UUID/URL, image or video — type auto-detects) for a specific file; generate_cover_image:true for an AI cover (add generate_cover_image_prompt — recommended); omit both for a stock search. @mentions: @StyleName (list_styles) and @[Name](item:UUID) — sheet only (list_collection_items); gallery rejected. With post_type 'carousel' these also reach the slides. Credits scale with platform count. Returns a job_id — poll get_jobs; result_metadata has { postIdeaId, redirectUrl }; use get_post to fetch content.

generate_post

Generate a video using AI (one of the most expensive actions, ~12 credits) — state the plan and get the user's explicit yes BEFORE calling. Returns a job_id — poll get_jobs; result auto-saves as a video asset. Models (`model` enum) differ in resolution/duration/aspect/ref limit/audio — omit for the default. No reference images + frames on: Veo Fast, Veo Standard, Seedance 2.0 Fast, Seedance 2.0, Seedance 2.5 (other models allow both). Cost depends on model/duration/resolution, rising with a video reference. Credits reserve high, settle to the provider's actual bill, refund fully on failure — reserved is never final. get_jobs returns { videoId, assetId, signedUrl } — pass assetId as cover_media to update_post/create_post/set_social_post/update_social_post. Requires the `video_generation` feature.

generate_video

How the workspace's social posts are performing over a period — the same numbers as the Analytics page. Use it for "how are my posts doing?", "what's working?", "when should I post?", or to ground new post ideas in results. Returns JSON: status ('ok', or 'connect' / 'reconnect' / 'unavailable' / 'waiting' with a next_step sentence), range, updated_at, summary (per metric: current, previous, change, change_kind — 'pct' = percent change (16.0 means +16%), 'pts' = percentage points for engagement_rate / reach_rate / click_through_rate, which are percentages; 'abs' = plain difference for net_followers), platforms (per-platform totals), whats_working (plain-language insights), by_how_it_was_made (format / cover / topic vs the account's usual), best_times (best weekday + time windows), top_posts and lowest_posts (with published_post_id for get_post_performance), needs_reconnect, unavailable (per platform: why some metrics are missing), and daily (the day-by-day series, only with include_daily). null means no number — never treat it as 0: the platform doesn't report that metric yet, or a connected platform hasn't had its first sync (both explained in unavailable); change is also null when the previous period had nothing to compare against. `last_synced_at: null` means the first sync is still pending — numbers arrive within a few hours of publishing. On a synced post, a null metric = not reported by the platform, not zero. Engagements = likes + comments + shares + saves + clicks. "vs usual" compares a post with the same account's typical post at the same age (1.0 = typical). Read-only, free.

get_analytics_summary

Read the comments queued to publish under a post once it goes live (the "first comment" / link-in-comment). Returns them per platform with their delay and status. Call this FIRST when editing one specific existing comment: set_auto_comments replaces the whole list, so you need to send back the ones you are keeping.

get_auto_comments

Get background jobs for a workspace. Use this after calling a generation tool (generate_post, generate_carousel, create_campaign, generate_image, generate_cover_image, edit_image) to check whether it has completed, is still running, or has failed. When called with a job_id, returns that specific job. Without job_id, returns the latest 10 jobs. Each job includes status ('running', 'completed', 'failed') and result_metadata which contains the created resource IDs: - post_generation: { postIdeaId, redirectUrl } - campaign_v2_generate / campaign_v2_generate_posts: { campaignId, redirectUrl } - carousel_generation: { carousel_id, carousel_folder_id, redirectUrl } - image_generation: { assets: [{ asset_id, signed_url, storage_path }], count, credits_used, text_response } - cover_image_generation: { assets: [{ asset_id, signed_url, storage_path }], post_id, credits_used, text_response } - image_editing: { assets: [{ asset_id, signed_url, storage_path }], credits_used, text_response } - video_generation (MCP, auto-saved on completion): { videoId, assetId, signedUrl, storagePath, mimeType, prompt, durationSeconds, autoSaved: true } - video_generation (UI flow, awaiting save action): { tmpPath, signedUrl, mimeType, prompt, durationSeconds } Use the resource ID from result_metadata to fetch full details (e.g. get_post, get_campaign, get_carousel, get_asset).

get_jobs

Get details of a specific business asset by ID. Returns metadata (including when it was last used in a post, if ever), signed URL, and optionally the file content as base64. For documents with extracted text, the text is always included. Use list_assets first to find asset IDs. Set include_content=true to get the actual file bytes as an inline base64 content block (images render directly in MCP clients, other types returned as embedded resources). Useful when you need to see or process the file contents. Skipped for files over 10MB.

get_asset

Get the complete brand profile for the current workspace. Returns all brand identity data organized into sections: basic info (name, description, website, language, country, timezone), visual identity (color palette with primary/secondary/accent/background/text colors, font family), communication tone (formality, energy, personality, voice description, syntax preferences, preferred and banned phrases), brand remarks (brandRemarks — standing facts and current priorities the business says must never be got wrong; set via update_brand_remarks), cover image guidelines (coverGuidelinesEmpty for default auto-generation, coverGuidelinesGeneral for rules always applied — both may contain @mentions in @[DisplayName](scheme:uuid) format referencing collection items, styles, and assets), marketing goals, target audience description, and competitor analysis. photoRules: the owner's explicit photo rules; null or absent = never chosen. Change them only with update_photo_rules, and only when the owner explicitly asks. Fields like targetAudience, competitors, brandRemarks and cover guidelines may be null/empty if not yet configured — use update_brand_identity to set cover guidelines, update_brand_remarks for remarks, update_target_audience and update_competitors for those fields. Use this to understand the full brand context before creating or updating content. The profile is automatically used by AI when generating posts and campaigns to keep content on-brand.

get_brand_profile

Get full details of a specific campaign by its ID. Returns the campaign metadata (title, description, status, time period, goals, strategy, frequency) and all its post ideas with their platform-specific social posts. Use this after creating a campaign to inspect the generated plan, or to review a campaign's content and publishing progress.

get_campaign

Get full carousel details including all slides with signed image URLs.

get_carousel

Get a single collection item in FULL detail — all its gallery images (with ids, captions, order), its full metadata, reference_sheet_status, and the collection's metadata_schema. ALWAYS call this before manage_collection_item action 'update' or 'remove_image': updates replace fields and metadata is replace-not-merge, so you must read current values (and image ids) first to avoid wiping them. Identify the item by item_id alone (from list_collection_items). Each gallery image includes its "caption", its "visual_description" (AI-facing scene/appearance text), a signed "url", and a ready-to-paste "mention" (item_image: scheme) — paste it verbatim into any prompt that RENDERS an image to use ONLY that one photo: image, cover and video generation, a carousel slide, and edit_carousel_slide. It costs exactly one reference, so it fits where a whole gallery item does not. Only post-body and campaign text reject it — those are written from words, not pictures.

get_collection_item

Read the words currently written ON a post's cover image (or on each slide of a carousel), with the node id that carries each line. Call this before rewording anything the user has not quoted to you exactly, and use the ids it returns with set_cover_text — never invent one. NOT for the post's hook or caption: those are the text published WITH the post - change them with update_social_post. A carousel's hook SLIDE is the exception: it is slide 1 of the deck. Each line comes back as { node_id, role, text }. `role` is "headline" or "subhead" when the cover still uses the standard copy layer, and is ABSENT when it does not (a visual template replaces those ids) — in that case read the text itself to tell the title from the subtitle. THIS IS ALSO THE TEST FOR WHETHER THE WORDS CAN BE EDITED AT ALL. Call it FIRST when the user asks to change the words on the image (they said image, cover, photo, picture, slide or overlay), and read the result: • text_nodes present → the words are editable text over the photo. Change them with set_cover_text. Free and instant. • text_nodes EMPTY → the words are painted into the photo itself. Nothing can edit them; the only way to change them is to regenerate the picture with the new wording — update_post({ generate_cover_prompt }) for a post cover, or edit_carousel_slide({ slide_number, text }) for a deck slide. Both COST CREDITS and produce a DIFFERENT picture, so tell the user that and get their go-ahead before calling either. You cannot read what such a cover currently says from any tool — look at the cover image (cover_url from get_post) or ask the user.

get_cover_text

Get the full details of a single brain memory by ID, including the complete content that gets injected into AI prompts. Use this to inspect what the AI will see when this memory is @mentioned, or before updating/deleting it.

get_memory

Get a photoshoot and its photos (status per photo, the brand-media asset id, and a signed image URL for ready photos). Use the photoshoot_id from plan_photoshoot / start_photoshoot / list_photoshoots.

get_photoshoot

Resolve the photoshoot niche for a gallery item (or explicit niche_id) and return what a shoot can be configured with: the niche, its scene_controls, available looks/styles, and how many of the item's photos still need visual analysis (with the credit cost). Call before create_photoshoot to learn the valid `scene`.

get_photoshoot_options

A post is a group of platform-specific social posts (e.g., one for LinkedIn, one for Instagram). Get full details of a specific post by its post idea ID. Returns the post idea (title, description, status, cover image) and all its platform-specific versions with full content text, media URLs, publishing status, and scheduling info. Use this to review a post's content before publishing or to inspect published results. Social post statuses: draft, scheduled, pending_approval (awaiting workspace approval), published, declined, overdue, failed. Published platform versions include `performance` (same fields as list_post_performance items; null until the first sync, or if the platform isn't tracked); call get_post_performance for the growth curve.

get_post

Full performance for a published post: every metric, engagement rate, how it compares with the account's usual, how it was made (format, cover kind, topic), and how views and engagements grew over time (the 60 most recent snapshots). Pass exactly one of published_post_id (one platform) or post_id (a Beevi post: one entry per platform it went out on). Returns { posts: [{ post, curve: [{ captured_at, views, engagements }] }], unavailable, missing } — post has the same fields as list_post_performance items; only synced platforms are in posts. missing (post_id only, present when some published platforms have no numbers): [{ platform, reason }] — 'not_synced_yet' = the first sync is still pending (numbers arrive within a few hours of publishing), 'not_tracked' = this platform's numbers aren't tracked (Google Business, or published before analytics started). A null metric = not reported by the platform, not zero. Numbers refresh every 3 hours for the first 2 days, daily until day 30, weekly until day 90, then they're final (one last check at a year). Read-only, free.

get_post_performance

Generate a short-lived (15-minute) upload token so you can upload local files from your machine directly to the workspace asset library. Supports up to 14 files per request, images or videos (e.g. an MP4 to use as a post cover). Returns a token, upload URL, and a ready-to-use curl command. After upload completes, the response includes each file's asset UUID — pass that UUID to any tool that accepts an asset reference (edit_image, create_style, manage_collection_item, generate_video, generate_post, create_post, update_brand_basics, etc.). Use this when the user provides a local file and your client supports HTTP file uploads. For clients without programmatic upload support (e.g. Claude Desktop), instruct the user to upload via Brand Media in the Beevi web UI instead. Files land as the customer's own media (origin 'user'). Pass a `visual_description` field alongside each `file` (see the returned instructions) for photos you already looked at — that skips a paid AI describe run.

get_upload_token

Get the Weekly Compass for a workspace — the current week's bundle of "what to consider this week" signals, useful for deciding what to post about. Returns: - search_trends: rising search queries in the business's field, each with why_relevant, post_angle, momentum/score, and whether it's corroborated by the news - relevant_content: recent articles in the field, each with a summary, url, and why_relevant - calendar_events: upcoming synced calendar events + public holidays (title, date, type) - memories: the business's dated memories relevant to this window (each with an @[Name](memory:id) mention token) - overview: a short markdown digest of the strongest signals with one woven post idea (may be null) - week_key, generated_at, is_stale: metadata (is_stale = the cache is >10 days old) This is READ-ONLY — it reads the latest cached week plus live legs; it does not generate or refresh the Compass. All fields may be empty (arrays [], overview null, generated_at null) when the business hasn't opted into Weekly Compass or no weekly run has happened yet — that is expected, not an error.

get_compass

Get detailed information about the current workspace, including business profile (name, description, website, language, country, timezone) and connected social media platforms. Use this to check which platforms are connected before publishing posts, or to understand the workspace's configuration. No parameters needed — returns details for the workspace associated with the current API key.

get_workspace

List or search business files and folders. Browse: pass a path (empty = root). Search: pass a query to find assets by filename or description across all folders. Filter by type (image, document, etc.) or origin (user vs generated). Files that already appear in a post carry a `used` tag; pass unused=true to see only the never-used ones. Every image comes back with a ready-to-paste `@[filename](asset:UUID)` mention. Paste it VERBATIM into a generation prompt — generate_image, generate_cover_image, generate_video, generate_carousel (deck prompt or a slide), or edit_carousel_slide — and that exact picture is attached as a visual reference. Prefer this over describing the picture in words. Brand logo shortcut: instead of looking up the logo here, you can use @BrandLogo directly in generate_image or generate_cover_image prompts — it will be included as a visual reference automatically. If you still need to find it manually, it is under the Brand Assets directory as a file called logo (extension may vary). Every asset has an 'origin': 'user' = the customer put it here (uploads, chat attachments, logo, saved images); 'generated' = a model made it (AI covers, carousel slides, photoshoots, videos, assistant images). Origin is provenance and cannot be changed after upload.

list_assets

List campaigns in the workspace. A campaign is a coordinated, time-bound social media marketing initiative with a theme, goal, and a schedule of AI-generated post ideas across multiple platforms. Campaigns have a time period (start/end dates) and a status (planning, active, completed). Use this to review existing marketing plans and their progress. Returns campaigns with status, time period, and post idea counts.

list_campaigns

List carousels for a workspace with pagination. Returns carousel summaries (id, title, platform, slide count, cover image, date).

list_carousels

List items across the workspace's collections. Each has 'kind' (sheet|gallery) + 'mention'. Sheet: usable once 'ready'. Gallery: tagging spreads ALL images (rejected in post text/1 slide — tag ONE via item_image:UUID). SUMMARY only. Free-text 'tags' (≤10×40 chars, unique) — prefer per-type (character: Founder, Employee, Customer, Mascot, Model; product: Best seller, New, Seasonal, Signature; location: My business, Event venue, Neighborhood; property: For sale, For rent, Sold; screenshot: Desktop, Mobile, Tablet, New feature) else custom. 'My business' = the business's own premises.

list_collection_items

List the workspace's visual collections. A COLLECTION holds ITEMS of one "kind": 'sheet' (character/product/clothing/custom) = one identity-locked reference sheet per item, created async & credit-charged; 'gallery'/multi_image (property/location/screenshot) = a photo bundle, tagging spreads ALL images (rejected in post text or one carousel slide). 'mention' is the canonical handle — paste it VERBATIM. Each result has 'metadata_schema', 'kind', and — sheet only — a 'mention' casting all ready members. Call before creating items or tagging a whole collection.

list_collections

List brain memories stored in the workspace. A memory is a piece of knowledge about the business — a person, an event, a fact, or domain expertise — that gets injected into the AI's context when generating posts, campaigns, or images. When you @mention a memory in a prompt, its full content is appended to the generation context so the AI writes with that knowledge. For example, a 'persona' memory for 'Sarah CEO' would contain her bio, communication style, and key talking points. When @mentioned in generate_post, the AI writes as if it knows Sarah personally. Call this before generating content to discover what the business has taught the AI. Each result includes a 'mention' field (e.g. '@[Sarah CEO](memory:abc-123)') — use this value verbatim in the prompt of generate_post, create_campaign, or generate_image. You can also use the shorthand @MemoryName and it will be resolved automatically.

list_memories

List recent photoshoots in this workspace (newest first), each with its status, photo count, and a signed cover URL. Optionally filter by status.

list_photoshoots

List published posts — made with Beevi or posted directly on the platform — with their performance, sorted and paged. Use it to find the best or weakest posts, compare platforms, or get a published_post_id for get_post_performance. Each item: published_post_id, post_id (the Beevi post id for get_post; null for posts made outside Beevi), social_post_id, platform, origin, published_at, url, title, format, cover_kind, topic, metrics (views, reach, likes, comments, shares, saves, clicks, video_views, watch_time_ms), engagements, engagement_rate_pct, vs_usual (1.0 = typical for this account, 2.0 = twice its usual engagement, null until there's enough history), last_synced_at. Also pageInfo { limit, offset, total, hasMore }, unavailable (per platform: why some metrics are null), and note (only when the range has no published posts: what to call next). Only posts published inside the range are listed. `last_synced_at: null` means the first sync is still pending — numbers arrive within a few hours of publishing. On a synced post, a null metric = not reported by the platform, not zero. Read-only, free.

list_post_performance

A post is a group of platform-specific social posts (e.g., one for LinkedIn, one for Instagram). List posts in the workspace with optional filtering and sorting. Returns a slim summary by default (post_id, title, status, platforms, scheduled_at, created_at, cover_url). Supports filtering by status, scheduled date range, created date range, platform, and text search. All filters combine as AND conditions. Set include_content=true to get full platform-specific content text. Use get_post for complete details of a single post. Post statuses: draft (not yet scheduled), scheduled (approved, waiting to publish), pending_approval (awaiting workspace owner approval), published (live on platform), declined (rejected during approval), overdue (missed scheduled time without approval), failed (publishing error). Lifecycle groups (use the `lifecycle` param): needs_attention, upcoming, drafts, published.

list_posts

List image generation styles available in the workspace. A style defines a reusable visual aesthetic (e.g. 'Minimalist Corporate', 'Vibrant Pop Art') with a description and optional reference images. Styles ensure consistent visual branding across AI-generated images. Call this before generating images, posts, or campaigns to discover available styles. Each result includes a 'mention' field (e.g. '@[Watercolor](style:abc-123)') — use this value verbatim in the prompt of generate_image, generate_cover_image, generate_post, or create_campaign to apply that style. You can also use the shorthand @StyleName (e.g. @Watercolor) and it will be resolved automatically.

list_styles

List the visual cover-overlay templates available to this workspace: the business's saved templates plus built-in starter presets (discount, grand-opening, testimonial, etc.). Returns each template's opaque id, name, and kind. Copy an id VERBATIM into apply_visual_template — never invent or edit it.

list_visual_templates

List workspaces accessible to the authenticated user. A workspace represents a business brand — it contains the brand profile, posts, campaigns, styles, and visual collections. Use this first to get a workspace ID before calling other tools. Returns workspace IDs, names, and logos. Use the search parameter to filter by name instead of fetching all workspaces.

list_workspaces

Lock a photoshoot plan from the table you laid out in chat, WITHOUT generating anything yet. Returns a plan + credit estimate the user confirms. Pass `concept` (the agreed shared vibe + what must stay identical across the set) and `table` — the finished markdown table, one row per photo, columns: Concept | Subjects | World | Notes. Put @-mentions verbatim in the Subjects and World cells, e.g. @[Sophie](item:UUID) for a person/product and @[Gym Floor](item_image:UUID) or @[Villa](asset:UUID) for a scene. A row may be concept-only (no subjects, no world). Only item / item_image / collection / asset mentions are valid. Costs 0.5 credits (covers the planning AI); at most 20 table rows per call. After the user confirms, call start_photoshoot with the returned photoshoot_id.

plan_photoshoot