add_pipeline_entry
ChatGPTAdd a company or contact to a pipeline, optionally into a specific stage and with initial field values. A record sits on a pipeline at most once — adding one that is already present returns the existing entry unchanged (check its createdAt). Pipeline automations configured for 'record added' run on a genuine add.
add_ticket_tags
ChatGPTAdd tags to a ticket. New tags are merged with existing tags (no duplicates removed).
archive_ticket
ChatGPTArchive a ticket to remove it from active views. AGENT-RUN TICKETS: never archive a ticket you are resolving — Gleap owns the lifecycle after your registered PR merges.
ask_code
ChatGPTAsk a natural-language question about how the project's product works. Analyzes all source repositories that are connected to this project and returns an explanation of user-facing logic and click paths. Only available when the project has at least one connected code repository — if no repos are connected, the tool returns a message saying so. Never returns code, file paths, identifiers, or secrets — only product behavior in plain English.
assign_ticket
ChatGPTAssign a ticket to a specific user or team. Use get_users or get_teams to find valid IDs.
close_ticket
ChatGPTClose a ticket. A plain close sets status DONE and fires the project's close workflows (e.g. CSAT). Pass asSpam:true for junk/spam instead: that archives it into the Spam review queue and never contacts the customer. AGENT-RUN TICKETS: never close a ticket you are resolving as a coding agent — not even after your reply is sent; Gleap closes it automatically after the post-merge follow-up or ship-message delivery. Call this only on a direct, explicit operator instruction.
configure_email_automation
ChatGPTSet a non-live email's event trigger (event, first/last occurrence, delay), frequency and audience. Never publishes; refuses live emails (pause_email first). Returns the saved settings.
configure_outbound_targeting
ChatGPTSet who gets a non-live outbound item and when: delivery (triggered or one-off), trigger event + delay, frequency, page rules, audience (identified users/guests + rules on events and contact attributes), schedule. Works for every outbound type. Find event/attribute names with get_targeting_options first; if what you need is not tracked, get_event_tracking_guide. Never publishes; refuses live items (pause_outbound first). Returns the saved targeting.
create_contact
ChatGPTCreate a new contact in Gleap.
create_feature_request
ChatGPTFile a new FEATURE_REQUEST ticket on the project's roadmap. The requesting customer becomes the request's creator (their session is attached) and first upvoter automatically. Use only after search_feature_requests returned no strong match. Pass the originating customer ticket id in linkedTicketIds. On success the response includes a shareUrl: reply with it verbatim, never construct roadmap URLs yourself. When existing requests match, NOTHING is created and the result is {ok: false, duplicate: true, candidates, hint}: subscribe the customer to the candidate that is their need (subscribe_to_feature_request with its id), or, when you compared the candidates and none is the same need (e.g. a different product surface), call create_feature_request again with their ids in notDuplicateOf.
create_help_center_article
ChatGPTCreate a new help center article. REQUIRED: title, description, and content (all localized objects; content = TipTap doc per locale). Optional: isDraft, targetAudience, tags, externalId. Do not call without title, description, and content.
create_help_center_collection
ChatGPTCreate a new help center collection. REQUIRED: title (localized object, e.g. { "en": "Name" }). Optional: description, iconUrl, parent, externalId, targetAudience. Do not call without title.
create_image_upload_link
ChatGPTCreate a single-use link (valid 15 minutes) that uploads ONE image from disk into this Gleap project, for agents that can run a shell command. Run the returned curl command with your file path; its JSON response carries fileUrl. PNG, JPEG, GIF and WebP up to 20 MB. Use fileUrl as coverImageUrl on create_news_draft / update_news_draft or as an image src in TipTap content. Images: upload first (upload_image, or create_image_upload_link for a file on disk), then add a top-level block node { "type": "imageBlock", "attrs": { "src": "<fileUrl>", "width": "100%", "align": "center", "alt": "<description>" } } between paragraphs (never inside one). width is a percentage string, align left|center|right; optional link + target ("_blank") make the image clickable.
create_news
ChatGPTCreate a new news or changelog entry. REQUIRED: name (string), subject (localized object, e.g. { "en": "What's New" }), and message (localized TipTap document). Do not call without all three required fields.
create_news_draft
ChatGPTSave an unpublished news draft in Gleap and return its reviewUrl. Does not publish, schedule, or send. After human approval of the plan, prepare the draft; obtain a separate approval of the completed content before publication in the dashboard. Requires name, localized subject, and localized TipTap message.
create_newsletter_draft
ChatGPTSave an unpublished newsletter draft in Gleap and return its reviewUrl. Does not publish, schedule, or send. After human approval of the plan, prepare the draft; obtain a separate approval of the completed content before publication in the dashboard. Requires name, localized subject, and localized TipTap message. The draft uses the project's default email template (the first in its template list, as the dashboard picks for a new email) unless emailTemplate names another of the project's templates.
create_outbound_draft
ChatGPTCreate an unpublished survey, chat message, banner, info card (modal), checklist, push notification, product tour or tooltip set, with its content, in the shape the dashboard editor writes. Put the content in the block named after the type (survey, chatMessage, banner, modal, checklist, push, productTour, tooltip). Text fields take plain text per locale. Nothing is shown to anyone: set who and when with configure_outbound_targeting, then publish_outbound after the operator approves. Returns reviewUrl.
create_ticket
ChatGPTCreate a new ticket in Gleap. Type and title are required. Use get_ticket_types to see available types and form data structure. The ticket counts as created by your team (like the dashboard's New ticket): it is not triaged as a customer report.
create_ticket_with_message
ChatGPTCreate a new ticket with an optional initial message in a single step. This is the recommended way to create tickets. Use get_ticket_types first to see available types and their form fields.
delete_news
ChatGPTPermanently delete a news or changelog item by ID. This action cannot be undone.
draft_reply_to_composer
ChatGPTStage a drafted reply in the ticket's dashboard composer for a human to review, edit and send — NOTHING is sent to the customer. The draft appears instantly in the composer of everyone viewing the ticket. IMPORTANT: call this only when staging a draft is explicitly called for — the user asked you to draft a reply, or the Gleap ticket-resolution workflow you are following instructs you to stage the reply in the composer (e.g. a drafted customer reply that was not approved for direct sending). Never draft proactively or as a side effect of an unrelated request. Replaces any existing draft on the ticket (so it can also be used to revise a draft); the draft is cleared automatically once a reply is sent or the team dismisses it in the composer. The text supports Markdown formatting.
find_tickets
ChatGPTList/FILTER tickets by structured fields (status, assignee, priority, tags, date range) — NOT free-text; for keyword search use search_tickets instead, and don't call both for the same intent. Archived tickets are left out unless includeArchived is true — set it for reports and complete counts. Returns lightweight summaries (id, title, status + human-readable statusLabel, priority + priorityLabel, assignee, tags, AI summary, form data, timestamps, dashboardUrl); call get_ticket afterwards for a match whose full content and conversation you need.
get_companies
ChatGPTList the project's companies (organisations), most recently seen first, optionally filtered by a name search. Each row carries two identifiers: id (the Gleap id — what pipeline tools take as recordId) and companyId (the external id your app sends via the SDK — what get_company/update_company take). Returns summaries; call get_company for the full record including custom data.
get_company
ChatGPTGet one company by its external companyId (the identifier your app sends via the SDK — not the Gleap id), including address and custom data. To find contacts belonging to it, use get_contacts with the same companyId.
get_contact
ChatGPTRetrieve a specific contact by ID from Gleap.
get_contact_tickets
ChatGPTGet all tickets associated with a specific contact. Useful for reviewing a customer's support history. Returns lightweight ticket summaries; call get_ticket for the full ticket and conversation.
get_contacts
ChatGPTFILTER contacts by structured fields (userId, name, companyId, companyName, email) with pagination — NOT free-text. For keyword search use search_contacts instead; don't call both for the same intent. Returns lightweight summaries (identity fields, company, plan, value, timestamps); call get_contact for the full contact including custom data.
get_email_automation
ChatGPTRead an email's status, trigger, frequency and audience (targetAudience + conditions), plus its dashboard reviewUrl.
get_event_tracking_guide
ChatGPTHow to start tracking an event or contact attribute that targeting needs but the project does not have yet: the call for each SDK (JavaScript, iOS, Android, Flutter, React Native) and from a backend, where to place it, and how to verify it arrived. Use it when get_targeting_options finds no fitting event/attribute; hand the snippet to the developer or a coding agent. Reports whether the name is already tracked.
get_feature_request
ChatGPTRead one feature request by id or ticket number ("#1234"): title, a description excerpt, roadmap status, upvote count and public share link. Use it when an investigation, a teammate or the thread cites a feature request, to confirm it is the customer's need before subscribe_to_feature_request (which takes the same id). Only feature requests of this project resolve. public: false means it is tracked but not on the public roadmap yet: no link and no status to share. Repeat shareUrl verbatim, never build roadmap URLs yourself.
get_help_center_article
ChatGPTRetrieve a specific help center article by ID.
get_help_center_articles
ChatGPTRetrieve articles in a help center collection with optional pagination. Returns lightweight summaries (title, description, slug, tags, draft state, timestamps); call get_help_center_article for the full localized article content.
get_help_center_collections
ChatGPTRetrieve help center collections from Gleap with optional pagination.
get_help_center_collections_tree
ChatGPTRetrieve all help center collections including subcollections in tree structure.
get_news
ChatGPTRetrieve news and changelog items from Gleap with optional pagination. Use withoutChangelogs to filter to news-only items. Returns lightweight summaries (name, subject, type, status, timestamps); call get_news_item for the full localized message body.
get_news_item
ChatGPTRetrieve a specific news or changelog item by ID.
get_newsletter_draft
ChatGPTRead a newsletter draft's full localized content and dashboard reviewUrl.
get_newsletter_drafts
ChatGPTList unpublished, fixed, one-time email campaigns. Returns summaries; use get_newsletter_draft for content and reviewUrl.
get_outbound_message
ChatGPTRead one outbound item: its content (survey questions included), its targeting (delivery, trigger, frequency, page rules, audience, schedule) and reviewUrl; optionally delivery statistics.
get_pipeline
ChatGPTGet one pipeline including its stages (in board order) and its fields. Entry values are keyed by each field's fieldId; a field's calculation (sum/count/average/min/max/filled/empty) is what get_pipeline_stats aggregates for it — fields without one are not aggregated.
get_pipeline_entries
ChatGPTList a pipeline's entries — every record on the pipeline with its stage and field values. Pass stageId to list one stage (board order); omit it to list across all stages with a total for pagination. Each entry carries a record snapshot (name, plan, value) of its company/contact.
get_pipeline_entry
ChatGPTGet one pipeline entry together with its pipeline (stages and record type) — the full context needed to move it or update its values.
get_pipeline_stats
ChatGPTPer-stage entry counts and field aggregations for a pipeline, plus whole-pipeline totals — e.g. the sum of deal values in each stage. Aggregations cover the fields with a calculation configured (see get_pipeline); to aggregate a field without one, list the entries with get_pipeline_entries and compute from their values. Averages in totals are true pipeline-wide averages, not an average of the stage averages.
get_pipelines
ChatGPTList the CRM pipelines visible to this connection. Each pipeline holds records of exactly one type (recordType COMPANY or CONTACT) and carries its stages in order — pass a stage id as stageId when adding or moving entries. Call get_pipeline for a pipeline's fields (needed for entry values). Only pipelines that are public or explicitly shared with this connection's user are listed, so a pipeline the user expects may be missing because it is private — in Gleap, open the pipeline's settings and make it public or share it.
get_raw_data_statistics
ChatGPTRetrieve individual event rows (the raw log the aggregated statistics are computed from) from Gleap. Every filter is ANDed; unset filters are not applied, so a call with only a date range returns every kind of event in that period. Returns up to 10 000 rows, unpaginated and unsorted, with UTC timestamps — narrow the period or add filters rather than paging. Prefer get_statistics_facts / get_statistics_bar_chart when a count or a trend is all you need.
get_record_pipelines
ChatGPTWhich pipelines a company or contact is on, with its entry (stage and values) in each — e.g. to check whether a company is already in the sales pipeline before adding it.
get_statistics_bar_chart
ChatGPTRetrieve bar chart statistics from Gleap. Use chartType to specify the type of chart data you want.
get_statistics_facts
ChatGPTRetrieve fact-based statistics from Gleap. Use chartType to specify the type of metric you want.
get_statistics_list
ChatGPTRetrieve list-based statistics from Gleap. Use chartType to specify the type of list data you want.
get_survey_responses
ChatGPTGet responses for a specific survey with pagination. Each response is returned as a lightweight summary; the survey answers are in formData. Use get_survey_summary for an AI overview.
get_survey_summary
ChatGPTGet an AI-generated summary of survey responses.
get_surveys
ChatGPTList available surveys in the project.
get_targeting_options
ChatGPTWhat outbound messages (surveys, emails, banners, chat messages, checklists, tours, tooltips, info cards, push, news) can target in this project: the events contacts have sent (usable as triggers and event rules) and the contact attributes (usable as audience rules), with the condition syntax. Call it before configure_outbound_targeting or configure_email_automation. When nothing fits the audience you need, it says so; then use get_event_tracking_guide.
get_teams
ChatGPTGet all teams in the project with their members. Useful for finding the right team to assign a ticket to.
get_ticket
ChatGPTRetrieve the full ticket by ID — content, conversation, form data, and all other fields, plus a human-readable statusLabel / priorityLabel and a dashboardUrl deep link. Use this after find_tickets when the slim summary isn't enough. If your prompt already contains this ticket's injected context sections (Kai resolution runs inject the full ticket + conversation), do not re-fetch that same ticket — use this for OTHER tickets, e.g. matches from search_tickets/find_tickets.
get_ticket_activity_log
ChatGPTBug reports: call this before you try to reproduce, to see the console errors, failed network requests and the user's click trail. It returns what the Gleap SDK captured in the customer's app with the ticket: console logs, network requests (method, URL, status, duration) and the click trail (clicks, page views, custom events), oldest first. Request and response headers are never returned, secrets (tokens, API keys, passwords, cookies, card numbers) are replaced with [redacted], and bodies are included for failed requests and for requests matching search. Long logs are trimmed: errors and failed requests are kept first, then the newest entries, and the summary says how many of each kind were shown (N of M). For more, including entries left out, use section (console, network or actions) or search (an error message, URL or status code). This is not the ticket's conversation (use get_ticket_messages) and has no status or assignment history. If it returns a plan error (402), continue without logs.
get_ticket_messages
ChatGPTGet the full conversation history (messages) for a specific ticket in chronological order — user messages, AI bot answers, and human agent replies. Each message includes the visible text as plain text (TipTap/markdown flattened), the author (senderType: user/agent/bot/system, plus the sender id), AI answer signals (answerBot, hasAnswer, and cited sources), attachments, and timestamps. If your prompt already contains this ticket's conversation, call this only to page OLDER history beyond what was injected (skip/limit), never to re-read what you already have.
get_ticket_types
ChatGPTGet the project's boards (ticket types): each one's custom data attributes (schema + example, for building formData), its configured status lanes (statuses: key + human-readable title + hidden flag), its priorities (priorities: key + title + archived + isDefault, most urgent first), and its dashboard URL segment (path). Call this whenever you need to explain, choose, or list ticket statuses or priorities — custom lanes and priorities have opaque generated keys (38jd9, p_…) whose only readable form is the title returned here. Archived priorities stay on existing tickets but can't be set.
get_users
ChatGPTGet all support agents and users in the project. Useful for finding who to assign a ticket to.
get_workflows
ChatGPTList all workflows (workflow-type bots) in the project, both live and draft. Use this for a full inventory. To start a workflow on a ticket use get_workflows_available_for_ticket (only live workflows on a ticket with a contact can be started), then run_ticket_workflow.
get_workflows_available_for_ticket
ChatGPTList the workflows that can actually be started on a specific ticket — i.e. the exact set run_ticket_workflow accepts. These are the project's live workflows, but only if the ticket has an associated contact; a ticket without a contact returns an empty list (nothing can be started on it).
link_tickets
ChatGPTLink two related tickets together for reference.
list_outbound_messages
ChatGPTList one outbound type (survey, chat_message, banner, modal, checklist, product_tour, tooltip, news, email, push, whatsapp), newest first, with status, delivery mode, trigger and reviewUrl.
merge_tickets
ChatGPTMerge duplicate tickets into a single target ticket. Source tickets will be closed and linked to the target.
move_pipeline_entry
ChatGPTMove a pipeline entry to another stage of its pipeline — e.g. advance a deal from 'Negotiation' to 'Won'. Moving to a new stage runs the pipeline automations configured for that stage.
pause_email
ChatGPTTake a live email off (the dashboard's Unpublish): it stops sending and pending sends are dropped. Settings and content stay. Already-sent one-offs cannot be paused.
pause_outbound
ChatGPTTake a live outbound item off (the dashboard's Unpublish): it stops showing/sending and pending deliveries are dropped; content and targeting stay. Sent one-offs cannot be paused.
preview_outbound_audience
ChatGPTCount who an outbound item's audience rules match right now, with a few sample contacts; nothing is saved or sent. Pass audience to try other rules before saving. For a one-off this is the recipient list at publish; for a triggered item it is who can receive it once the trigger fires. Emails count only contacts with an email, WhatsApp only those with a phone.
publish_email
ChatGPTSet an email live, through the dashboard's publish path. Requires an event trigger; refuses one-off sends unless oneOffAudience confirms a narrowed users/guests audience. Only after the operator approved publishing. Returns the live settings.
publish_outbound
ChatGPTSet an outbound item live through the dashboard's publish path. Only after the operator approved publishing this item. Checks it has content and a trigger, and that the audience rules are complete. Sends that go to the whole audience at once (one-offs, news with push) also need confirmedReach: the approved count from preview_outbound_audience. Email/push one-offs never go to everyone without rules. For emails, publish_email works too.
remove_pipeline_entry
ChatGPTRemove an entry from its pipeline. Only the pipeline membership is deleted — the underlying company or contact is untouched.
reopen_ticket
ChatGPTReopen a closed ticket by setting its status to OPEN.
report_progress
ChatGPTReport your working status on a ticket you are actively resolving. Updates the ticket's live activity badge in the Gleap dashboard (state, not chat — it overwrites the previous status and never posts a message). This is your ONLY status surface: put the detail in the message (on 'blocked' say what you need from a human; on 'done' give a one-line root cause + fix) — do NOT post internal notes for status or findings. Call it at phase TRANSITIONS only: when you start (investigating), when you confirm the issue (reproduced), while implementing (fixing), when the PR is up (pr_opened — always pass prUrl; a registered PR lets Gleap follow up with the customer after the merge and close the ticket itself, so never close it yourself), when you need a human (blocked), and when your work is finished (done). With pr_opened/done you may also pass customerShipMessage — your pre-drafted 'the fix shipped' customer message, sent automatically after the merge (see the parameter for the approval rule). It is an EXTRA on top of your normal customer reply (sent or staged via send_message/draft_reply_to_composer), never a replacement for it. The result includes a 'Ship message:' line telling you what happened to it (parked until merge / armed / refused) — relay that to your operator and never follow up with a manual send. Always pass the same sessionId so parallel agents on one ticket don't overwrite each other. Do not call it for every small step. (send_message is reserved for the immediate customer reply.)
run_ticket_workflow
ChatGPTManually start a workflow on a ticket — the equivalent of the ⚡ 'Start a workflow' action inside a ticket. Only a live workflow that is available for the ticket can be started (call get_workflows_available_for_ticket first). The workflow runs asynchronously against the ticket's contact; a success response means it was accepted, not that it has finished.
search_contacts
ChatGPTFree-text KEYWORD search for contacts (name, email, etc.). Use when you have a search term. To filter contacts by specific fields (userId, companyId, companyName, email), use get_contacts instead — don't call both for the same intent. Returns lightweight summaries (identity fields, company, plan, value, timestamps); call get_contact for the full contact including custom data.
search_feature_requests
ChatGPTSemantic dedupe search over the project's feature requests (OpenSearch fuzzy match + Voyage AI rerank): up to 5 matches, best first, each with its rerank score. Call this BEFORE create_feature_request. Matches with public: false are tracked but not on the public roadmap yet (e.g. just filed into the intake lane): subscribing the customer works, but they have no share link and no status to state. For public matches, status is the customer-facing roadmap label (when null, state no status) and shareUrl the public link: repeat it verbatim, never build roadmap URLs yourself. ranked: false means the reranker was unavailable and the matches are keyword hits: judge them by title and description. To read a feature request you already have an id for, use get_feature_request. If the response contains searchUnavailable: true, the dedupe index could not be queried — do NOT proceed to create_feature_request; retry the search later or escalate to the team.
search_knowledgebase
ChatGPTSearch the project knowledge base (help center articles, custom documents, code knowledge) using semantic vector search. Returns the most relevant content for answering questions. For multi-part questions, split into separate focused calls (max 2).
search_similar_tickets
ChatGPTFind resolved tickets with similar issues using semantic vector search. Use this to discover how similar customer problems were solved in the past.
search_tickets
ChatGPTFree-text KEYWORD search across ticket title, body, and messages. Use when you have search terms. Do NOT also call find_tickets for the same intent (that one is for structured field filters, not keywords). Returns lightweight match summaries (id, title, status + human-readable statusLabel, priority + priorityLabel, type, tags, a content preview, relevance score, dashboardUrl); call get_ticket afterwards for a match you need to inspect in full.
send_message
ChatGPTSend a reply to a customer on a ticket, or add an internal note. The text supports Markdown formatting (bold, italic, links, lists, headings, code). Use isNote=true for internal notes that the customer won't see. WORKFLOW RULE (agent-run tickets): a customer-visible reply requires your operator's explicit approval of the exact text — without it, stage the draft with draft_reply_to_composer instead of sending; workflow customer replies stay plain text (no markdown). Never use send_message to announce a merged/shipped fix when a customerShipMessage was passed to report_progress — that scheduled message already covers the announcement, and a manual send would double-message the customer.
snooze_ticket
ChatGPTSnooze a ticket for a specified duration in minutes. The ticket will be hidden until the snooze period ends. Not part of agent ticket workflows — when you are resolving a ticket and waiting on a human, use report_progress phase 'blocked' instead of snoozing.
subscribe_to_feature_request
ChatGPTIdempotently add a customer's email to a feature request's upvoter list. Safe to call repeatedly — no-ops when the customer is already subscribed. Use this after search_feature_requests finds a strong duplicate so the customer gets notified when it ships.
unarchive_ticket
ChatGPTUnarchive a previously archived ticket to restore it to active views.
update_company
ChatGPTCreate or update a company by its external companyId (upsert). Only name, plan, domain, value, address and customData are accepted; address and customData are merged into the existing values rather than replaced. Setting a non-empty name marks it authoritative, so names sent by the SDK will no longer overwrite it.
update_contact
ChatGPTUpdate a contact's properties such as name, email, phone, company, tags, custom data, plan, or value.
update_help_center_article
ChatGPTUpdate an existing help center article. REQUIRED: title, description, and content (localized objects; content = TipTap doc per locale). Do not call without all three.
update_help_center_collection
ChatGPTUpdate an existing help center collection in Gleap.
update_news
ChatGPTUpdate an existing news or changelog entry by ID.
update_news_draft
ChatGPTRevise an existing unpublished news draft. Checks its type and draft status before writing; refuses live, paused, or sent items. Cannot publish, schedule, or send. Returns reviewUrl for human review.
update_newsletter_draft
ChatGPTRevise an existing unpublished newsletter draft. Checks its type and draft status before writing; refuses live, paused, or sent items. Cannot publish, schedule, or send. Returns reviewUrl for human review. emailTemplate switches the draft's email template. A draft stored without one gets the project's default template on any update, so calling with only draftId repairs a draft that opens with an empty editor.
update_outbound_content
ChatGPTChange the content of a non-live survey, chat message, banner, info card (modal), checklist, push notification, product tour or tooltip set. Fields you send replace the stored ones (steps, questions and tooltips as a whole list); others stay. Refuses live items (pause_outbound first). Targeting is changed with configure_outbound_targeting.
update_pipeline_entry_values
ChatGPTUpdate a pipeline entry's field values (e.g. set a deal value). Sent keys are merged into the existing values — fields you do not send are left untouched — and sending null clears a field. Keys must be the pipeline's field fieldIds (see get_pipeline).
update_ticket
ChatGPTUpdate a ticket's properties such as status, priority, assignee, tags, title, due date, or custom form data. status must be an exact lane KEY (e.g. '38jd9'), never the label shown in statusLabel — call get_ticket_types for the ticket's board to look the key up. A status that isn't one of that board's lane keys makes the ticket vanish from every board view. priority takes a key or title from the board's priorities (get_ticket_types); an unknown or archived one is rejected.
upload_image
ChatGPTStore an image in this Gleap project's CDN and return its permanent fileUrl, for news/changelog covers (coverImageUrl) and images inside TipTap content (news, newsletters, help center articles). Pass exactly one of data (base64) or url (public http(s) URL). PNG, JPEG, GIF and WebP only, judged by the bytes. For a file on disk (e.g. a generated cover), prefer create_image_upload_link — base64 in a tool call is slow and costly. Images: upload first (upload_image, or create_image_upload_link for a file on disk), then add a top-level block node { "type": "imageBlock", "attrs": { "src": "<fileUrl>", "width": "100%", "align": "center", "alt": "<description>" } } between paragraphs (never inside one). width is a percentage string, align left|center|right; optional link + target ("_blank") make the image clickable.
