MCP tools

Every action an AI assistant can take in Luminobot, what kind of action it is and which safety modes allow it.

For developers

AI assistants work in Luminobot through tools: small actions such as "list conversations" or "schedule a post". Your assistant picks the right tool by itself — you just ask in plain words. This page lists every tool so you know what is possible and what each safety mode allows.

How to read this list

Each tool has a kind:

  • read — only looks things up. Allowed in every mode.
  • write — changes something inside Luminobot only, such as a label, a note, a contact or a draft. Allowed in drafts-only and full mode.
  • send — reaches a customer, for example a reply. In drafts-only mode, replies become drafts a person approves; other send tools are refused.
  • publish — puts a post live on a network. In drafts-only mode, scheduled posts become drafts that go to approval.
  • admin — approvals, deletions, consent changes and webhooks. Full mode only.

On top of the mode, a tool only works if the connection has the permission for it (the tool's description says which), and you can switch single tools off for a connection under Safety on its page. Switched-off tools disappear from the assistant's list.

The list below is built from Luminobot itself, so it is always current.

There are 85 tools. Each one has a kind — read, write, send, publish or admin — and the connection's safety mode decides which kinds an assistant may use. Every tool that works in one workspace also takes an optional workspace argument (the workspace id or its exact name); it is required when a connection covers more than one workspace.

Workspaces & people

list_accounts — List accounts

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

List the social media accounts this API key is allowed to act on. Returns id, platform, account_name, account_handle, connection_status, char_limit, needs_title, supports_first_comment and connection_warnings. Call this first to discover which social_account_id values are valid and what each platform requires. A non-empty connection_warnings list means posts to that account will fail until a person reconnects it in the app; tell the user instead of scheduling to it.

No parameters.

list_members — List workspace members

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

List the workspace's members (id, name, email, role) — use an id as assigned_to_id in update_message or as an assignee of a post. me is the user this connection acts as.

No parameters.

list_workspaces — List workspaces

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

List the workspaces this connection can act in, with its permissions and number of accounts in each, plus the connection's safety mode (full / drafts_only / read_only). When there is more than one, pass workspace (id or name) to every other tool.

No parameters.

Inbox

add_internal_note — Add internal note

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

Add an internal note to a conversation (visible to teammates only, never sent to the customer). @mention a teammate by email to notify them. Requires reply_from_inbox and the note capability.

Parameters:

  • message_id (id, required)
  • text (text, required, up to 2000 characters)

apply_macro — Apply macro

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

Apply a macro to a conversation: its actions run now (only those the key may do on the account) and its filled-in reply text is returned — it is NOT sent. Send it with reply_to_message, passing deferred_token as macro_token, so the closing actions (resolve, archive, snooze) run after the send. Requires reply_from_inbox.

Parameters:

  • message_id (id, required)
  • macro_id (id, required)

bulk_update_conversations — Change many conversations at once

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

Run one action on up to 200 conversations (any message id of a conversation stands for it): resolve, reopen, archive, mark_read, mark_unread, assign (user_id; omit to unassign), assign_team (team_id), priority (low/normal/high/urgent, empty clears), add_label / remove_label (label id or name), snooze (preset 1h/3h/tomorrow/next_week/1w). Requires use_inbox + reply_from_inbox; each conversation needs the account capability (close / assign / note) and must be in the issuer's inbox scope. Returns done, skipped (with reason) and not_found per id.

Parameters:

  • action (text, required, one of resolve, reopen, archive, mark_read, mark_unread, assign, assign_team, priority, add_label, remove_label, snooze)
  • message_ids (list of id, required, up to 200 items)
  • user_id (id, optional)
  • team_id (id, optional)
  • label (text, optional, up to 50 characters)
  • priority (text, optional, one of "", low, normal, high, urgent)
  • preset (text, optional, one of 1h, 3h, tomorrow, next_week, 1w)
  • idempotency_key (text, optional, up to 255 characters) — Optional. Retrying with the same key returns the first answer instead of running again.

get_conversation — Read a conversation

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Read the conversation around an inbox message: inbound messages and our replies (with delivery_status sent/delivered/read/failed), oldest first. Requires use_inbox.

Parameters:

  • message_id (id, required)
  • before (text, optional) — ISO-8601 cursor: the next_before value of the previous page.
  • limit (whole number, optional, 1 to 100, default 50)

get_csat — Customer satisfaction (CSAT)

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Customer satisfaction (CSAT): with message_id, that conversation's survey status, 1-5 rating and comment (requires use_inbox); without it, a summary for the last days days on this key's accounts — surveys sent, answered, average and % rating 4-5 (requires view_analytics).

Parameters:

  • message_id (id, optional)
  • days (whole number, optional, 1 to 365)

get_sla_status — SLA status

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

A conversation's SLA status: the SLA policy it got, its first-response, next-response and resolution due times (breached or not), the nearest pending target and whether the clock is paused outside business hours, plus any active snooze. Requires use_inbox.

Parameters:

  • message_id (id, required)

label_conversation — Add or remove conversation labels

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

Add and/or remove labels on a conversation, e.g. {message_id, add: ['refund'], remove: ['new']}. Unknown labels are created. Requires reply_from_inbox and the key's note capability on the account.

Parameters:

  • message_id (id, required)
  • add (list of text, optional, up to 10 items)
  • remove (list of text, optional, up to 10 items)

list_conversations — List conversations

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

List inbox conversations (latest message per conversation, newest first) across the allowlisted accounts: Facebook Messenger, Instagram, WhatsApp, Telegram DMs plus comments, mentions and Google reviews. Each item has id (a message id to pass to the other inbox tools), platform, message_type, status, sender, body, assignee, priority, labels, unread_count; reviews add stars (1-5) and review (location, link, current public reply). Filters combine, e.g. {status: 'open', awaiting_reply: true, assigned_to: 'unassigned'} = open chats nobody answered yet; {sla: 'breached'} = overdue ones. Requires use_inbox.

Parameters:

  • social_account_id (id, optional) — Only this allowlisted account.
  • status (text, optional, one of unread, open, resolved, archived)
  • message_type (text, optional, one of dm, comment, mention, review)
  • platform (text, optional) — Channel, e.g. whatsapp, instagram, facebook, telegram, webchat, sms, email.
  • assigned_to (text, optional) — 'me', 'unassigned' or a member id.
  • label (text, optional) — Only conversations with this label (name).
  • sla (text, optional, one of breached, due_soon) — Open conversations past an SLA target, or due within the hour.
  • awaiting_reply (true/false, optional) — Only conversations where the customer is waiting for our answer.
  • q (text, optional, up to 100 characters) — Search message text and sender.
  • stars (list of whole number, optional, up to 5 items) — Only Google reviews with these star ratings, e.g. [1, 2].
  • before (text, optional) — ISO-8601 cursor: the next_before value of the previous page.
  • limit (whole number, optional, 1 to 100, default 25)

list_inbox_teams — List inbox teams

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

List the workspace's inbox teams: routing mode (manual / round_robin / least_open), the accounts and labels they cover, members with state (online / away / offline) and open conversation load, and how many conversations wait unassigned. Requires use_inbox.

No parameters.

list_labels — List labels

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

List the workspace's conversation labels (name, color). Requires use_inbox.

No parameters.

list_macros — List macros

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

List inbox macros (shared ones + the key issuer's personal ones): name, reply_body, actions (label, status, priority, assign, note, snooze) and a readable action_summary. With message_id each reply comes filled in for that conversation. Requires use_inbox.

Parameters:

  • message_id (id, optional)

list_saved_replies — List saved replies

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

List the workspace's saved replies with their placeholders ({first_name}, {agent_name}, {field:<key>} …) filled in for the conversation of message_id. Send an item's text with reply_to_message; anything listed in unfilled was left as typed and should be edited first. Requires use_inbox.

Parameters:

  • message_id (id, required)

private_reply_to_comment — Private reply to a comment

Kind: send — reaches customers. Safety modes — Read only: no · Drafts only: no · Full: yes.

Send a private (DM) reply to the author of a Facebook/Instagram comment. Meta allows one per comment, within 7 days. Requires reply_from_inbox.

Parameters:

  • message_id (id, required)
  • text (text, required, up to 2000 characters)

reply_to_message — Reply to a message

Kind: send — reaches customers. Safety modes — Read only: no · Drafts only: saves a draft for approval · Full: yes.

Reply to an inbox message: a DM gets a message in the same conversation, a comment or mention gets a public reply. Platform rules apply (Messenger/Instagram 24-hour window; WhatsApp allows only templates after 24h; expired connections must be reconnected) — a refusal comes back with isError and an explanation. Requires reply_from_inbox.

Parameters:

  • message_id (id, required)
  • text (text, required, up to 4096 characters)
  • macro_token (text, optional) — deferred_token from apply_macro: the macro's resolve/snooze run after this send.

route_to_team — Route to team

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

Hand an inbox conversation to a team: the team's routing picks an available member (status 'assigned'), or the conversation waits in the team queue until someone is available (status 'queued'). Requires reply_from_inbox and the key's assign capability.

Parameters:

  • message_id (id, required)
  • team_id (id, required)

send_email — Send a new email

Kind: send — reaches customers. Safety modes — Read only: no · Drafts only: no · Full: yes.

Send a NEW email (not a reply) from a connected email inbox (an allowlisted account with platform 'email', see list_accounts). It starts a conversation in the inbox and the customer's answer comes back into it; to answer an existing email use reply_to_message. Signature and sender name come from the inbox settings. Requires reply_from_inbox and the direct_messages capability on the account.

Parameters:

  • social_account_id (id, required) — The email inbox's account id.
  • to (list of text, required, up to 50 items) — Recipients, e.g. ['jane@example.com', 'Bob <bob@example.com>'].
  • cc (list of text, optional, up to 50 items)
  • subject (text, required, up to 250 characters)
  • text (text, required, up to 50000 characters)

snooze_conversation — Snooze conversation

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

Hide a conversation from the open inbox views until a time (it comes back then, or as soon as the customer writes). Give one of: until (ISO 8601; no offset = workspace time zone), preset (1h, 3h, tomorrow, next_week, 1w) or minutes (5 to 129600). The result warns when the 24-hour reply window (WhatsApp / Messenger / Instagram) closes during the snooze. Requires reply_from_inbox.

Parameters:

  • message_id (id, required)
  • until (text, optional)
  • preset (text, optional, one of 1h, 3h, tomorrow, next_week, 1w)
  • minutes (whole number, optional, 5 to 129600)
  • note (text, optional, up to 200 characters)

unsnooze_conversation — Unsnooze conversation

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

End a conversation's snooze now (it shows in the inbox again). Requires reply_from_inbox.

Parameters:

  • message_id (id, required)

update_message — Update conversation (status, assignee, priority)

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

Set an inbox message's status, assignee (a workspace member) and/or conversation priority (empty string clears it). Requires reply_from_inbox.

Parameters:

  • message_id (id, required)
  • status (text, optional, one of unread, open, resolved, archived)
  • priority (text, optional, one of "", low, normal, high, urgent)
  • assigned_to_id (id, optional)
  • unassign (true/false, optional, default false)

AI help

decide_ai_action — Approve or reject an AI action

Kind: admin — approvals, deletions, consent, webhooks. Safety modes — Read only: no · Drafts only: no · Full: yes.

Approve or reject an AI Employee action waiting for approval. The AI then continues the conversation (approved actions run; rejected ones are skipped, with your note). Recorded in the activity log. Requires reply_from_inbox and reply access on the account.

Parameters:

  • action_id (id, required)
  • decision (text, required, one of approve, reject)
  • note (text, optional, up to 500 characters)
  • digest (text, optional, up to 64 characters) — The action's digest from list_ai_actions; approving fails if it changed since.

list_ai_actions — List ai actions

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

List actions AI Employees want to take on conversations (add a label, assign, internal note) and their approval status. Default: actions waiting for approval. Requires use_inbox.

Parameters:

  • status (text, optional, one of awaiting_approval, approved, rejected, completed, failed, expired, all)
  • limit (whole number, optional, 1 to 100)

repurpose_content — Repurpose content

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

Turn a URL (the workspace's own sites; others need allow_third_party=true and the rights to reuse them) or a long text into one draft per account: a thread for X/Threads/Bluesky/Mastodon, a carousel outline for Instagram/LinkedIn, a short-video script for TikTok/YouTube, a post elsewhere, in the brand voice. Returns text; with create_drafts=true each is saved as a DRAFT post (never scheduled). Uses AI credits. Requires create_posts.

Parameters:

  • social_account_ids (list of id, required, up to 20 items)
  • url (text, optional, up to 2000 characters)
  • text (text, optional, up to 24000 characters)
  • tone (text, optional)
  • allow_third_party (true/false, optional)
  • create_drafts (true/false, optional)

suggest_reply — Suggest reply

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Draft a reply to an inbox conversation from its history, the workspace's knowledge and brand voice. Returns text only — nothing is sent; review it and send with reply_to_message. Uses AI credits. Requires reply_from_inbox.

Parameters:

  • message_id (id, required)
  • notes (text, optional, up to 1000 characters) — What the reply should say.

summarise_conversation — Summarise conversation

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Summarise an inbox conversation in a few bullets (uses AI credits). Requires use_inbox.

Parameters:

  • message_id (id, required)

translate_message — Translate message

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Translate text (default: the customer's latest message in the conversation) into a language. Uses AI credits. Requires use_inbox.

Parameters:

  • message_id (id, required)
  • language (text, required, one of English, Spanish, French, German, Italian, Portuguese, Dutch, Polish, Turkish, Arabic, Urdu, Hindi, …)
  • text (text, optional, up to 6000 characters)

write_captions — Write captions

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Write social captions from a brief: one shared caption plus one tailored to each account (network length limits, hashtags, YouTube/Pinterest titles) in the workspace's brand voice. Nothing is saved; pass the text to create_draft or schedule_post. Uses AI credits. Requires create_posts.

Parameters:

  • brief (text, required, up to 6000 characters)
  • social_account_ids (list of id, required, up to 20 items)
  • tone (text, optional, one of brand, friendly, professional, playful, bold, informative, inspirational, urgent)
  • length (text, optional, one of short, medium, long)
  • hashtags (text, optional, one of brand, none, few, many)

Contacts

export_contact_data — Export contact data

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Export everything stored about one contact for a privacy (data access) request: profile, channel identities, consent status and history, conversations with replies, internal notes, broadcasts, drips and workflow runs. Logged in the activity log. Requires manage_contacts.

Parameters:

  • contact_id (id, required)

get_contact — Get contact

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Read a contact with its platform identities and recent messages. Requires use_contacts.

Parameters:

  • contact_id (id, required)

list_segments — List segments

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

List the workspace's saved contact segments (rule-based groups) with their live sizes. Requires use_contacts.

No parameters.

search_contacts — Search contacts

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Search contacts reachable through this key's accounts by name, phone, email or handle. Requires use_contacts.

Parameters:

  • q (text, optional)
  • before (text, optional) — ISO-8601 cursor: the next_before value of the previous page.
  • limit (whole number, optional, 1 to 100, default 25)

set_contact_consent — Set contact consent

Kind: admin — approvals, deletions, consent, webhooks. Safety modes — Read only: no · Drafts only: no · Full: yes.

Mark a contact opted in, opted out or unknown for messages (e.g. they asked to unsubscribe). Opted-out contacts get no broadcasts, drip steps or proactive workflow messages; replies to their own new messages are still allowed. Opting in clears earlier STOP replies on every channel — only do it with the person's permission. Logged. Requires manage_contacts.

Parameters:

  • contact_id (id, required)
  • status (text, required, one of opted_in, opted_out, unknown)
  • note (text, optional, up to 255 characters) — Why (kept in the consent log).

update_contact — Update contact

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

Update a contact's name, phone, email, lifecycle stage (lead / prospect / customer / vip) and tags (add_tags / remove_tags), e.g. {contact_id, lifecycle_stage: 'customer', add_tags: ['vip']}. Fields you leave out stay as they are. Requires manage_contacts.

Parameters:

  • contact_id (id, required)
  • display_name (text, optional, up to 255 characters)
  • primary_phone (text, optional, up to 20 characters)
  • email (text, optional, up to 254 characters)
  • lifecycle_stage (text, optional, one of lead, prospect, customer, vip)
  • add_tags (list of text, optional, up to 20 items)
  • remove_tags (list of text, optional, up to 20 items)

Workflows

decide_workflow_approval — Approve or reject a workflow step

Kind: admin — approvals, deletions, consent, webhooks. Safety modes — Read only: no · Drafts only: no · Full: yes.

Approve or reject a workflow approval as the key's issuer (who must be one of its approvers). The workflow then continues down its Approved / Rejected path; decisions after the time-out are refused. For AI agent actions pass the digest you reviewed. Recorded in the activity log. Requires use_workflows or approve_posts.

Parameters:

  • approval_id (id, required)
  • decision (text, required, one of approve, reject)
  • comment (text, optional, up to 2000 characters)
  • fields (object, optional)
  • digest (text, optional)

get_workflow — Get workflow

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Read one workflow: status, live version, triggers (e.g. message_received, manual), whether it can be run on demand (can_run_manually), its steps and recent run outcomes. Requires use_workflows.

Parameters:

  • workflow_id (id, required)

get_workflow_run — Get workflow run

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Read one workflow run with each step's status, output and error. Requires use_workflows.

Parameters:

  • run_id (id, required)

list_workflow_approvals — List workflow approvals

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

List workflow approvals (Request approval steps and AI agent actions) waiting for the key's issuer — or everyone's with everyone=true (needs use_workflows). Each shows its fields (editable ones can be changed when approving) and, for AI agent actions, every argument of every call plus a digest. Requires use_workflows or approve_posts.

Parameters:

  • status (text, optional, one of pending, approved, rejected, expired, cancelled, all)
  • everyone (true/false, optional)
  • limit (whole number, optional, 1 to 100)

list_workflow_runs — List workflow runs

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

List recent workflow runs (newest first), optionally for one workflow or by status (completed, failed, waiting, running …). Requires use_workflows.

Parameters:

  • workflow_id (id, optional)
  • status (text, optional, one of completed, failed, completed_errors, waiting, running, cancelled, filtered_out, no_trigger_match)
  • limit (whole number, optional, 1 to 100)

list_workflow_versions — List workflow versions

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

List a workflow's published versions (number, note, author, date; the live one is marked). Requires use_workflows.

Parameters:

  • workflow_id (id, required)
  • limit (whole number, optional, 1 to 100)

list_workflows — List workflows

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

List the workspace's workflows with their status, published version number and whether the draft has unpublished changes. Requires use_workflows.

No parameters.

publish_workflow — Publish workflow

Kind: admin — approvals, deletions, consent, webhooks. Safety modes — Read only: no · Drafts only: no · Full: yes.

Publish a workflow's current draft as a new version: it goes live and the workflow is switched on. Errors block; warnings need confirm_warnings=true. Recorded in the activity log. Requires manage_workflows.

Parameters:

  • workflow_id (id, required)
  • note (text, optional, up to 200 characters)
  • confirm_warnings (true/false, optional)

restore_workflow_version — Restore workflow version

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

Copy an earlier version of a workflow into its draft (nothing is published; call publish_workflow to make it live). Requires manage_workflows.

Parameters:

  • workflow_id (id, required)
  • version (whole number, required, at least 1)

run_workflow — Run a workflow now

Kind: send — reaches customers. Safety modes — Read only: no · Drafts only: no · Full: yes.

Run an active workflow that has a Manual trigger, now — for a conversation (message_id) or a contact (contact_id, its latest conversation is used), or with no target. It runs for real: its steps may message the customer. Returns the run id and status; check details with get_workflow_run. Requires manage_workflows.

Parameters:

  • workflow_id (id, required)
  • message_id (id, optional)
  • contact_id (id, optional)

Publishing

assign_post — Assign post

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

Put people on a post or take them off: owner (one), collaborators, reviewers (asked to review), engagement owner (one member or inbox team — comments on the published post are routed to them), and the content 'ready by' date (due_at, ISO 8601; null clears). Owner / engagement replace the current one. Assigning yourself needs create_posts; anyone else, edit_others_posts or approve_posts. Assignees are notified. Returns the post with its assignees.

Parameters:

  • post_id (id, required)
  • add (list of object, optional, up to 20 items)
  • remove (list of object, optional, up to 20 items)
  • due_at (date and time, optional)

bulk_update_posts — Change many posts at once

Kind: admin — approvals, deletions, consent, webhooks. Safety modes — Read only: no · Drafts only: no · Full: yes.

Run one action on up to 200 posts: reschedule (mode shift + amount + unit hours/days, or mode date + date YYYY-MM-DD keeping each network's local time), schedule (drafts at their time, else the account's queue), unschedule (back to drafts), delete, approve (posts waiting for approval), assign_owner (user_id), set_category (category_id), clear_category. Requires create_posts (approve: approve_posts); every post follows the composer's rules (publishing needs publish_directly + the account's publish capability). Returns done, skipped (with reason; partial when only some networks changed) and not_found per id.

Parameters:

  • action (text, required, one of reschedule, schedule, unschedule, delete, approve, assign_owner, set_category, clear_category)
  • post_ids (list of id, required, up to 200 items)
  • mode (text, optional, one of shift, date)
  • amount (whole number, optional, -8784 to 8784)
  • unit (text, optional, one of hours, days)
  • date (date, optional)
  • user_id (id, optional)
  • category_id (id, optional)
  • idempotency_key (text, optional, up to 255 characters) — Optional. Retrying with the same key returns the first answer instead of running again.

cancel_post — Cancel post

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

Cancel a scheduled post, transitioning it back to draft. No-op error if there are no scheduled children to cancel.

Parameters:

  • post_id (id, required)

comment_on_idea — Comment on idea

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

Comment on an idea. Comments are team-only; on a client content request, visibility 'external' shows the comment to the client in the portal. mention_ids (member user ids) notify those members when their @Name is in the body.

Parameters:

  • idea_id (id, required)
  • body (text, required, up to 4000 characters)
  • visibility (text, optional, one of internal, external)
  • mention_ids (list of id, optional, up to 20 items)

complete_post_reminder — Complete post reminder

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

Mark a 'Remind me' post as posted (optionally with the live post's URL) or skip it. Requires publish_directly.

Parameters:

  • reminder_id (id, required)
  • published_url (text, optional, up to 1000 characters)
  • skip (true/false, optional)

create_draft — Create draft

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

Create a draft post against a connected account. The draft is saved but not queued for publishing; call schedule_post or the schedule tool later to publish.

Parameters:

  • social_account_id (id, required) — ID of a SocialAccount in this key's allowlist (see list_accounts).
  • caption (text, required, up to 10000 characters)
  • title (text, optional, up to 255 characters)
  • first_comment (text, optional) — Optional comment auto-posted after the main post.
  • media_asset_ids (list of id, optional) — MediaAsset UUIDs already uploaded to the workspace's media library.
  • post_format (text, optional, one of feed, reel, story) — Instagram / Facebook only: publish as a feed post (default), Reel or Story.
  • platform_options (object, optional) — Instagram: collaborators (up to 3 usernames, not on Stories), user_tags ([{username, x, y}]), location_id (Facebook Page id), alt_text, trial_strategy (MANUAL or SS_PERFORMANCE, Reels only), audio_name, music_audio_id. YouTube: category_id, playlist_id, publish_at (ISO 8601), privacy_status, made_for_kids. Pinterest: board_id (required), link_url, alt_text, cover_image_asset_id (video Pins). Google Business: location_ids (required), topic_type (STANDARD, EVENT or OFFER), cta_type (BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP, CALL), cta_url, event_title, event_start, event_end (local YYYY-MM-DDTHH:MM), offer_coupon, offer_terms, offer_url.

decide_post_approval — Approve or reject a post

Kind: admin — approvals, deletions, consent, webhooks. Safety modes — Read only: no · Drafts only: no · Full: yes.

Approve, request changes on, or reject a post waiting for review (status pending_review / pending_client), as the user this connection acts for. An approved post with a requested time is scheduled automatically when the approver may publish. Requires approve_posts.

Parameters:

  • post_id (id, required)
  • decision (text, required, one of approve, request_changes, reject)
  • comment (text, optional, up to 2000 characters)

delete_post — Delete post

Kind: admin — approvals, deletions, consent, webhooks. Safety modes — Read only: no · Drafts only: no · Full: yes.

Delete a post and all its per-account versions from Luminobot (nothing is removed on the social platform). Needs the delete_posts permission, except for unpublished posts the key's issuer wrote. Deleting an already-published post also needs the issuer's right to publish to that account.

Parameters:

  • post_id (id, required)

get_link_clicks — Get link clicks

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Short-link clicks of a post: each tracked link with all-time clicks and clicks in the last days days (bots, link previews and repeat clicks aren't counted). Requires view_analytics.

Parameters:

  • post_id (id, required)
  • days (whole number, optional, 1 to 365)

get_media — Get media

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Retrieve a single media asset by id. Same response shape as GET /api/v1/media/{id}. Use this to poll an upload's processing_status until it transitions from 'pending' to 'completed'.

Parameters:

  • media_id (id, required)

get_post — Get post

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Retrieve a post by ID, including aggregate status and per-platform child state. Returns 'Post not found' for posts outside the API key's allowlist (same as for truly nonexistent IDs — the API never reveals which is which).

Parameters:

  • post_id (id, required)

get_post_checklist — Get post checklist

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

A post's checklist: items (text, done, who ticked it), done/total, and whether the workspace blocks scheduling until the checklist is done.

Parameters:

  • post_id (id, required)

list_hashtag_groups — List hashtag groups

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

The workspace's saved hashtag groups (from the brand kit). Requires create_posts.

No parameters.

list_ideas — List ideas

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Ideas on the workspace's ideas board, newest first: title, description, column, assignee, due date, the post it became and, for client content requests, the request status / wanted date / links. assigned_to_me limits to ideas assigned to the key's issuer; requests_only to client requests.

Parameters:

  • assigned_to_me (true/false, optional)
  • requests_only (true/false, optional)
  • limit (whole number, optional, 1 to 100)

list_my_posts — List my posts

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Posts the API key's issuer is on (any role, or one role), soonest 'ready by' date first. Published posts are left out unless include_published is true.

Parameters:

  • role (text, optional, one of owner, collaborator, reviewer, engagement)
  • include_published (true/false, optional)
  • limit (whole number, optional, 1 to 100)

list_post_reminders — List post reminders

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

'Remind me' posts that a person must finish in the network's app (Facebook groups, trending audio, link stickers…). status: sent (waiting), done or skipped. Requires create_posts.

Parameters:

  • status (text, optional, one of sent, done, skipped)

list_posts — List posts (calendar)

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

List posts this connection can read. With from/to (dates like 2026-11-02 or ISO times) it's the calendar: posts scheduled or published in that range, earliest first; otherwise the newest posts. Filter by status (draft, pending_review, scheduled, published, failed …) or social_account_id. Example: {from: '2026-11-02', to: '2026-11-08', status: 'scheduled'}.

Parameters:

  • from (text, optional)
  • to (text, optional)
  • status (text, optional, one of draft, pending_review, pending_client, approved, changes_requested, rejected, scheduled, publishing, published, failed)
  • social_account_id (id, optional)
  • limit (whole number, optional, 1 to 100, default 50)

list_utm_presets — List utm presets

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

List the workspace's UTM presets (utm_source/medium/campaign/content/term templates with variables like {network} and {campaign}) used when a post has 'Track links' on.

No parameters.

schedule_draft — Schedule draft

Kind: publish — puts content live. Safety modes — Read only: no · Drafts only: saves a draft for approval · Full: yes.

Schedule an EXISTING draft post — transitions every draft child to scheduled at the given UTC timestamp. Use this for the two-step flow 'create_draft now, schedule_draft later'. For one-shot create-and-schedule, use schedule_post instead. Requires both create_posts and publish_directly.

Parameters:

  • post_id (id, required)
  • scheduled_at (text, required) — ISO 8601 UTC timestamp (e.g. 2026-06-01T14:00:00Z)

schedule_post — Schedule post

Kind: publish — puts content live. Safety modes — Read only: no · Drafts only: saves a draft for approval · Full: yes.

Create a post and schedule it to publish at a specific UTC timestamp. The publisher polls every ~15s and will fire the post once the time elapses.

Parameters:

  • social_account_id (id, required)
  • caption (text, required, up to 10000 characters)
  • scheduled_at (text, required) — ISO 8601 UTC timestamp (e.g. 2026-06-01T14:00:00Z)
  • title (text, optional, up to 255 characters)
  • first_comment (text, optional)
  • media_asset_ids (list of id, optional)
  • post_format (text, optional, one of feed, reel, story) — Instagram / Facebook only: publish as a feed post (default), Reel or Story.
  • platform_options (object, optional) — Instagram: collaborators (up to 3 usernames, not on Stories), user_tags ([{username, x, y}]), location_id (Facebook Page id), alt_text, trial_strategy (MANUAL or SS_PERFORMANCE, Reels only), audio_name, music_audio_id. YouTube: category_id, playlist_id, publish_at (ISO 8601), privacy_status, made_for_kids. Pinterest: board_id (required), link_url, alt_text, cover_image_asset_id (video Pins). Google Business: location_ids (required), topic_type (STANDARD, EVENT or OFFER), cta_type (BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP, CALL), cta_url, event_title, event_start, event_end (local YYYY-MM-DDTHH:MM), offer_coupon, offer_terms, offer_url.

search_media — Search media

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Find media assets already uploaded to this workspace. Defaults to the 20 most recent assets that are ready to reference. Use this before uploading to avoid duplicating evergreen content. Returns the same item shape as GET /api/v1/media/.

Parameters:

  • query (text, optional) — Optional substring match on filename and tags.
  • media_type (text, optional, one of image, video, gif, document)
  • tags (list of text, optional) — All tags must match (AND semantics).
  • folder_id (id, optional)
  • is_starred (true/false, optional)
  • limit (whole number, optional, 1 to 100, default 20)

suggest_post_times — Suggest post times

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Best times to post for each account, learned from the account's own engagement by weekday/hour (network averages until there's enough data), plus the next three suggested times in the workspace timezone. Requires create_posts.

Parameters:

  • social_account_ids (list of id, required, up to 20 items)

update_draft — Edit a post that isn't published

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

Change the caption, title, first comment or media of a post that isn't published yet (drafts, posts in review, scheduled posts). To change the publish time, cancel_post then schedule_draft. Requires create_posts; someone else's post also needs edit_others_posts.

Parameters:

  • post_id (id, required)
  • caption (text, optional, up to 10000 characters)
  • title (text, optional, up to 255 characters)
  • first_comment (text, optional, up to 10000 characters)
  • media_asset_ids (list of id, optional, up to 20 items)

update_idea — Update idea

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

Set an idea's assignee (a member's user id or email; null clears) and/or due date (due_at, ISO 8601; null clears). Taking an idea yourself needs create_posts; assigning someone else needs edit_others_posts or approve_posts. Assigning accepts a new client request. Returns the idea with its comments.

Parameters:

  • idea_id (id, required)
  • assignee (text, optional, up to 254 characters)
  • due_at (date and time, optional)

update_post_checklist — Update post checklist

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

Change a post's checklist: add an item (add: text), or tick an item off / on (item_id + done) and/or rename it (item_id + text). Adding and renaming need the right to edit the post; reviewers and approvers may also tick items off. Returns the checklist.

Parameters:

  • post_id (id, required)
  • add (text, optional, up to 200 characters)
  • item_id (id, optional)
  • done (true/false, optional)
  • text (text, optional, up to 200 characters)

upload_media — Upload media

Kind: write — changes data inside the app. Safety modes — Read only: no · Drafts only: yes · Full: yes.

Upload a small media file (≤1 MB raw / ~1.3 MB base64) via base64. For anything larger use POST /api/v1/media/ over REST instead — multipart can't ride a JSON-RPC envelope. Returns the same shape as the REST upload response; processing_status starts at 'pending' until the background task transitions it to 'completed'.

Parameters:

  • filename (text, required, up to 255 characters)
  • content_base64 (text, required) — Base64-encoded file content. Decoded size must be ≤5 MB.
  • content_type (text, optional)
  • alt_text (text, optional, up to 2000 characters)
  • title (text, optional, up to 255 characters)
  • folder_id (id, optional)
  • tags (list of text, optional)

Analytics, competitors & ads

get_account_analytics — Get account analytics

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Read a channel's analytics summary over a rolling window: hero KPI metrics (views/likes/reach/etc.), an engagement-rate card when the platform supports it, and follower growth. Each metric is returned as {value, delta, series, kind} where delta is the percent change vs. the prior equal-length window and series is the daily sparkline. Includes captured_at and next_sync_eta so an agent can pick a sensible poll delay. Platforms without an analytics surface (LinkedIn Personal, Bluesky, Mastodon) return analytics_available`: false`` with unavailable_reason```. Requires the view_analytics permission.

Parameters:

  • account_id (id, required) — SocialAccount ID. Must be in this API key's allowlist.
  • days (whole number, optional, 7 to 90, default 30) — Rolling window size in days. 7, 30, and 90 are the typical values.

get_ad_insights — Get ad insights

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Spend, impressions, clicks and results of an ad account per campaign / ad set / ad for a date range. Read-only and cached; if status is 'loading', call again in a few seconds. Requires view_analytics.

Parameters:

  • ad_account_id (id, required)
  • range (text, optional, one of today, yesterday, last_7d, last_30d, this_month, last_month, custom)
  • since (date, optional)
  • until (date, optional)
  • level (text, optional, one of account, campaign, adset, ad)

get_competitor_stats — Get competitor stats

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

One competitor's daily history (followers, media count, averages, engagement rate, posts per week) for the last N days and its latest posts with links and likes/comments/views. Requires view_analytics.

Parameters:

  • competitor_id (id, required) — From list_competitors.
  • days (whole number, optional, 1 to 90, default 30)

get_insights — Get insights

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

AI insights for a period of the workspace's analytics compared with the previous period: a headline, 3-5 findings that each cite one number from the data (cites), 2-3 recommended actions and caveats (e.g. channels without analytics). Covers channel metrics, top/lowest posts, best posting times, inbox volume, response times and CSAT. Cached per period; writes new insights (using AI credits) only when none exist, the numbers changed, or refresh=true. Every number in the text is checked against the data. Requires view_analytics.

Parameters:

  • days (whole number, optional, one of 7, 30, 90, default 30) — Last N full days.
  • start (date, optional) — Custom period start (with end).
  • end (date, optional) — Custom period end, inclusive.
  • social_account_ids (list of id, optional) — Limit to these accounts (default: every account in the key's allowlist).
  • refresh (true/false, optional, default false) — Rewrite even if cached (rate-limited).

get_post_analytics — Get post analytics

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Read a post's analytics, broken down per platform. For each PlatformPost child returns the latest value and a since-publish daily sparkline for every metric the platform reports, plus captured_at and next_sync_eta for polling. Drafts and scheduled posts return an empty metric_tiles array (not an error), so this tool is safe to call in a polling loop right after schedule_post. Platforms without analytics (LinkedIn Personal, Bluesky, Mastodon) carry ```analytics_available: false`` per child. Requires the view_analytics` permission.

Parameters:

  • post_id (id, required) — Parent Post ID (the same one returned by create_draft / schedule_post).

list_ad_accounts — List ad accounts

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

List the Meta (Facebook / Instagram) ad accounts connected to the workspace. Requires view_analytics.

No parameters.

list_ad_leads — List ad leads

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Newest Lead Ads form submissions with their answers and linked contact. Requires use_contacts.

Parameters:

  • limit (whole number, optional, 1 to 100)
  • before (date, optional)

list_competitors — List competitors

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Competitors tracked in this workspace (public Instagram Business/Creator accounts and YouTube channels) next to your own Instagram/YouTube accounts, with their latest daily numbers: followers, 7- and 30-day growth, posts per week, average likes/comments/views and engagement (likes + comments) per post over the latest posts, engagement rate (% of followers), status and last refresh. Read-only; numbers refresh once a day. Requires view_analytics.

Parameters:

  • network (text, optional, one of instagram, youtube) — Default: both.

Webhooks

create_webhook — Create webhook

Kind: admin — approvals, deletions, consent, webhooks. Safety modes — Read only: no · Drafts only: no · Full: yes.

Subscribe a public https endpoint to events (e.g. post.published, message.received). Returns the signing secret ONCE — store it to verify X-Webhook-Signature (HMAC-SHA256 of '<t>.<body>'). Events are limited to this key's allowlisted accounts and permissions. Requires manage_workspace_settings.

Parameters:

  • name (text, required, up to 100 characters)
  • url (URL, required)
  • event_types (list of text, required, one of post.created, post.scheduled, post.published, post.failed, post.approved, post.rejected, message.received, conversation.assigned, conversation.resolved, csat.received, ai_action.awaiting_approval, contact.created, …)

delete_webhook — Delete webhook

Kind: admin — approvals, deletions, consent, webhooks. Safety modes — Read only: no · Drafts only: no · Full: yes.

Remove a webhook and its delivery log. Requires manage_workspace_settings.

Parameters:

  • webhook_id (id, required)

list_webhook_deliveries — List webhook deliveries

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

Recent deliveries of a webhook (newest first): event, status pending/delivered/failed, attempts, HTTP code, error, next retry. Requires manage_workspace_settings.

Parameters:

  • webhook_id (id, required)
  • status (text, optional, one of pending, delivered, failed)
  • event_type (text, optional)
  • limit (whole number, optional, 1 to 200)

list_webhooks — List webhooks

Kind: read — only looks things up. Safety modes — Read only: yes · Drafts only: yes · Full: yes.

List this workspace's outbound webhooks (event subscriptions): name, endpoint host, events, status, last error. Requires manage_workspace_settings and an org owner/admin issuer.

No parameters.

redeliver_webhook — Redeliver webhook

Kind: admin — approvals, deletions, consent, webhooks. Safety modes — Read only: no · Drafts only: no · Full: yes.

Queue one delivery to be sent again (same X-Webhook-Id, so the endpoint can ignore repeats). Requires manage_workspace_settings.

Parameters:

  • webhook_id (id, required)
  • delivery_id (id, required)

update_webhook — Update webhook

Kind: admin — approvals, deletions, consent, webhooks. Safety modes — Read only: no · Drafts only: no · Full: yes.

Change a webhook's name, endpoint URL or events, or pause (is_active=false) / resume it. Requires manage_workspace_settings.

Parameters:

  • webhook_id (id, required)
  • name (text, optional, up to 100 characters)
  • url (URL, optional)
  • event_types (list of text, optional, one of post.created, post.scheduled, post.published, post.failed, post.approved, post.rejected, message.received, conversation.assigned, conversation.resolved, csat.received, ai_action.awaiting_approval, contact.created, …)
  • is_active (true/false, optional)

Ready-made prompts

Assistants that support MCP prompts show these as shortcuts (in Claude they appear in the prompt menu).

  • Triage my inbox (triage_inbox) — Sort open and unread conversations by urgency, label and assign them, and draft replies. Arguments: workspace, limit.
  • Reply to unanswered messages (reply_to_unanswered) — Answer conversations still waiting for us, respecting 24-hour windows and saved replies. Arguments: workspace, max_replies.
  • Draft next week's posts (draft_weekly_posts) — Plan next week's posts at the best times and save them as drafts for review. Arguments: workspace, topic, posts_per_account.
  • Weekly performance summary (weekly_performance_summary) — Summarise last week's social and inbox performance with concrete next steps. Arguments: workspace, days.