Decktopus AI

Check the AI credit balance for the workspace. You MUST call this before generate_ai_deck_style or create_ai_deck, and you MUST tell the user the results in plain language (balance, cost per slide, affordable slides, estimated total). If canGenerateStyle is false, do NOT proceed — tell the user they need more credits. If hasEnoughCredits is false, warn them and offer alternatives (fewer slides, different workspace, or adding credits). Style generation is free but requires at least one slide worth of credits or it stalls in AWAITING_FINALIZATION. Credits are spent per rendered slide when the deck is created.

check_ai_credits

Generate an AI presentation deck from a prompt. PREREQUISITE: call check_ai_credits first and confirm the user has enough credits. Do NOT call this if hasEnoughCredits was false. Never retry after an ambiguous failure — poll get_ai_deck_status instead (retrying spends credits again). Runs the full pipeline (style -> blueprint -> outline -> enqueue) and returns a deckId and shareUrl as soon as the deck is queued for rendering. Slide images render in the background — poll get_ai_deck_status with the returned deckId to track progress. Choose the style via styleSource: "existing" (provide styleId), "topic" (a style is generated from the prompt), or "url" (a style is generated from brandUrl). If organizationId is omitted and the user belongs to organizations, one is selected automatically; the organizationId actually used is returned in the response.

create_ai_deck

Get a short-lived, presigned URL for uploading a presentation into the user Decktopus storage, so a deck they already have (or one you just wrote) can be brought into Decktopus without them saving and re-uploading it by hand. Accepts HTML, PDF and PPTX. Upload the bytes yourself with a plain HTTP PUT to the returned `uploadUrl` (no auth header, no special headers needed), then pass the returned `fileUrl` to `import_ai_deck_from_file`. The URL expires in 5 minutes — call this tool again if the upload has not started by then. Uploading costs no AI credits. If you cannot make an HTTP request yourself, skip this tool and send the markup inline as the `html` argument of `import_ai_deck_from_file` instead (HTML only).

create_file_upload_url

Generate a new AI Deck visual style from either a brand website URL or a topic description. IMPORTANT: Before calling, you MUST tell the user which source you chose (brand URL vs topic) and why. Brand URL (source:"url") pulls real logo/colors/fonts — use when a company website is available. Topic (source:"topic") invents a look from a visual brief — use when no website exists. Also call check_ai_credits first; if canGenerateStyle is false the style will stall. Returns a styleId immediately; generation runs asynchronously (1-3 min). Pass the returned styleId to create_ai_deck with styleSource:"existing" (deck creation waits for the style to finish).

generate_ai_deck_style

Read the viewer analytics of an AI Deck: how many people opened it, how long they stayed, the visit trend over time, the individual viewers (name/email when they identified themselves, location, device, which share link brought them), and per-slide engagement — how many visits reached each slide and how long they dwelled on it. Use it to answer "who viewed my deck", "how is my deck performing", "where do people drop off". Only tracked visits through a share link or the present view are counted; a deck nobody opened yet returns zeros. Pass a viewer id to get_ai_deck_viewer_analytics for that viewer's session-by-session detail.

get_ai_deck_analytics

Check the generation status of an AI Deck: overall state, per-slide progress counts, and the share URL. Call this repeatedly after create_ai_deck until the deck reaches a terminal state.

get_ai_deck_status

Drill into one viewer of an AI Deck: their totals plus every visit they made, slide by slide, with the dwell time on each slide and which slide they left on. Use it after get_ai_deck_analytics to answer "what did this person actually read" or "where did they stop". Takes the same period and share-link filters as get_ai_deck_analytics.

get_ai_deck_viewer_analytics

Turn an uploaded presentation into a Decktopus deck. Use this when the user already has the slides — as HTML, PDF or PPTX — instead of generating a deck from a prompt: no style, no credits and no rendering wait are involved, and the slides stay exactly as they are (HTML keeps one slide per section; PDF and PPTX keep one slide per page, imported as page images). Provide the deck either as `fileUrl` (call `create_file_upload_url`, PUT the file, pass the returned fileUrl) or as inline `html` for a small HTML document. PDF and PPTX take a few seconds to convert. Returns the deckId and a shareUrl straight away; the deck is a normal AI Deck afterwards, so list_ai_deck_share_links, create_ai_deck_share_link and get_ai_deck_analytics all work on it — that is how the user tracks who read the imported deck. Imported decks cannot be edited or regenerated by AI. If organizationId is omitted and the user belongs to organizations, one is selected automatically; the organizationId actually used is returned in the response.

import_ai_deck_from_file

List the completed AI Deck visual styles owned by the authenticated user (or an organization). Returns style IDs to pass as `styleId` to `create_ai_deck` with `styleSource: "existing"`.

list_ai_deck_styles

List the AI Decks the authenticated user owns or has been given access to, newest activity first. Use this to turn a deck name the user mentions into the `deckId` that get_ai_deck_analytics, get_ai_deck_status and the share-link tools need. Covers both the personal workspace and the user's organizations unless organizationId narrows it down.

list_ai_decks