flora_add_action
ChatGPTPlace a prebuilt action node on a project canvas. The node is inert until flora_run_canvas_action runs it; use flora_run_action instead to run an action headlessly with inline inputs.
flora_add_to_canvas
ChatGPTBefore creating a Deck, call flora_discover_skills with name="flora-deck-editor" and follow its workflow, including document readback. Add nodes and edges to a project canvas. A ref is optional for an unwired new node; omitted refs receive unique handles in created. Supply a unique ref when connect or group refers to a new node in this call. Use dedicated FLORA tools for canvas edits. Each add carries a type, an optional caller-chosen ref, and the node's prompt, model, params, or content_url (or, for a notes node, its text); resize a note with size, or fit_text:true to show the whole body without scrolling; flora_get_canvas reports the resulting size. Each connect wires two nodes, either an existing short id (n7) or a ref declared in the same call. Actions cannot connect directly to other actions. Run the source action first and wait for its outputs with flora_list_generations. A browser materializes its RESULT nodes; a headless run may finish without creating canvas result nodes. Read flora_get_canvas and connect a result node only if it exists. If absent, run the next action headlessly with flora_run_action using those output URLs/text as inline inputs. To continue a media chain on the canvas, add image/video/audio output URLs with flora_add_to_canvas using type and content_url, then connect the created node to the next action and run it. Adding a generation node does NOT run it — the node sits idle until flora_run_canvas_nodes starts it. For retries after a timeout, reuse idempotency_key so the API rejects a duplicate instead of creating copies. Finish a new batch with flora_arrange_canvas using the returned IDs, then read back to verify spacing. For incremental rows under an existing grid, match its column positions and gaps while keeping the existing nodes fixed. Graph positions are node anchors (usually top-center); layout.origin is the painted top-left: subtract half the first node width from its anchor x. Set gap to the existing distance between column anchors minus node width, not the default 64. For a new row, gap controls horizontal spacing only: set origin.y to continue the existing row-anchor interval, since horizontal and vertical gaps may differ. Never recreate existing nodes to organize them into fields. Prefer flora_organize_canvas_fields when advertised to reuse named frames, move existing IDs, and separate the fitted frames. If flora_update_canvas_nodes does not advertise group, preserve the nodes and explain that safe grouping is unavailable on this API. This is ADD-ONLY: it never updates or removes anything (edit existing nodes and edges with flora_update_canvas_nodes, delete nodes with flora_remove_from_canvas); a ref that matches a live node id is rejected. The response's created map gives each ref the short id and UUID the canvas assigned — use those for later reads and runs, never your refs. Omit position to place a node automatically below the existing canvas content; pass one only when the user asked for a specific spot. Warnings in the response mean part of the request was skipped (a duplicate edge, for instance), so a 200 with warnings is not a clean apply. Video-generation nodes require the workspace video entitlement; without it the whole changeset is rejected. Static video uploads via content_url are exempt. If rejected, ask the user to enable video access or build with image nodes; do not retry the unchanged request.
flora_app_check
ChatGPTLoad an app's current version in a headless browser under the same content security policy viewers get, and report what broke: console_errors, page_errors (uncaught exceptions), csp_violations (frames, media, fetches and eval the policy blocked), failed_requests, load_error, and screenshot_url (a 1280×800 PNG, signed for an hour). The page runs with a stand-in window.app: view access, empty app.db data, and app.flora calls that reject with unavailable_in_check, so data-driven parts show their empty or error state; don't count those as failures. Takes up to 45 seconds. Run it after flora_app_create or flora_app_update, fix what it reports, and check again. Needs edit access. Limited to 60 checks per person per hour: rate_limited carries retry_after_seconds, when the next check can run; temporarily_unavailable means the check couldn't run: say the page is unchecked.
flora_app_create
ChatGPTA free plan can have 2 live apps in the workspace. Deleting an app frees a slot; updating one does not count as a new app. At the limit this call is refused and names that limit. Tell the user to delete an app. A paid plan has no cap. flora_artifact_create is this same tool. Publish a single-file HTML app (a FLORA app) into a workspace as version 1. Returns artifact_id (art_…) and url, where workspace members open it in FLORA. You write the whole HTML; FLORA does not generate it. New apps are not shared: use flora_app_share for a link. To revise one, call flora_app_update with its artifact_id — never create a second app for a new version. Polls, sign-offs and approvals are apps too: record a final decision with app.db.commit. To remix someone else's app, read it with flora_app_get, then create your copy here with remixed_from_artifact_id and remixed_from_version set to the artifact_id and current_version that read returned; the original is never changed. HTML rules, checked before publish: one complete document (<!doctype html><html>…</html>), at most 2 MB of raw HTML (not its JSON-escaped size). Write the document straight into html; drafting it in a local file first means writing it twice. Scripts inline, or <script src> / module imports over https from cdnjs.cloudflare.com, cdn.jsdelivr.net/npm or unpkg.com only, each naming an exact version (name@1.2.3; never @latest, a range, /gh/ or /combine/), and every <script src> carries integrity="sha…-…" crossorigin="anonymous". Leave integrity off a <script src> and FLORA fills it in from the CDN's own listing: cdnjs files, unpkg files, and jsDelivr files the package ships. jsDelivr minifies a missing .min.js and builds +esm on the fly, so those have no hash and are refused: pin a file the package ships. To set integrity yourself, cdnjs lists sha512 SRI at https://api.cdnjs.com/libraries/<name>/<version>?fields=sri and jsDelivr lists base64 sha256 at https://data.jsdelivr.com/v1/package/npm/<name>@<version>/flat (integrity="sha256-<hash>"). No import() of a computed URL and no scripts created from code. No iframes, embeds or objects of other pages (YouTube, Maps, Figma: link out instead). Images, video and audio load only from FLORA media (asset and output URLs from the API), data: and blob: — upload any other file with flora_create_asset and use its url. Checked at view time only (publish does not catch these, the page just breaks): no eval or new Function (libraries that compile templates at run time, such as Alpine.js or Vue's in-browser compiler, fail), no fetch to hosts other than FLORA, and no media URLs set from script outside FLORA media. The page runs in an opaque-origin sandbox: no cookies, localStorage, sessionStorage or IndexedDB, and requests carry Origin: null — persist state with app.db, never browser storage. Fonts and stylesheets load from Google Fonts or those CDNs; forms never submit anywhere (handle submit in script). Links open in a new tab. A content check also refuses pages that ask for passwords or payment details, imitate a sign-in or brand page, navigate the top window or hide code with eval, carry harmful content, or start generations without a viewer's click: the error lists each content_policy.* finding with what to change. Neither check runs the page: a successful publish means the page is allowed, not that it works. Syntax-check inline scripts before publishing when you can (node --check), and tell the user what you could not verify. Large page (over about 100 KB) and a shell to run curl? Write it to a local file, reserve an upload with flora_app_reserve_upload, PUT the file with the curl command it returns, then publish with upload_id instead of html: the page is written once, never pasted into a tool call, and checked exactly like html. Without a shell, keep sending html (or edits to update). After publishing, call flora_app_check to load the page in a headless browser: it returns console errors, blocked loads and a screenshot. Fix what it reports before telling the user the page works. The page gets window.app at view time (do not include or…
flora_app_data_read
ChatGPTRead an app's data (what its page stores with app.db) as the signed-in user, without writing. Start with op collections when you don't know the collection names: it returns { collections: [{ name, count, bytes, updatedAt }] } and needs no collection. op get returns one Doc or null (needs id); list returns { docs, cursor } (limit, cursor, order_by); query returns { docs, cursor } filtered by where. Doc: { id, data, createdBy, createdAt, updatedAt }. Pass cursor from a previous result to page. Errors come back with the data service's code: not_found, invalid_argument, revoked, gone (app deleted). not_configured (temporarily_unavailable on older deployments) means this deployment has no data service; retrying won't help.
flora_app_data_write
ChatGPTWrite an app's data as the signed-in user; every open viewer sees the change live. op set creates or replaces a document (needs id and data), update shallow-merges data into an existing one (not_found if missing), delete removes it (returns { deleted }). Set and update return the Doc. op commit needs id and data: atomically creates the first decision in an EMPTY collection and permanently locks the entire collection against later writes, even different ids (conflict, 409); returns the Doc with server createdAt. Keep synthetic QA entries in a separate collection. Never fabricate a human choice or bypass a conflict using set or another collection. Needs edit access (forbidden otherwise). Limits: 256 KiB per document, 10,000 documents per collection; rate_limited means slow down. Read first with flora_app_data_read to match the shape the page expects; to seed a new app, use the shape its page writes (no read needed), and send several writes as one call with ops (up to 25), not one call per document. not_configured (temporarily_unavailable on older deployments) means this deployment has no data service: don't retry it or rewrite the page around it; report that seeding didn't happen.
flora_app_get
ChatGPTRead one app's metadata, and with include_html: true the current version's HTML — read it before editing so flora_app_update starts from what viewers see, or before remixing it with flora_app_create. Also reads, read-only, an app outside your workspaces whose share link you have opened in FLORA. A 404 means the id is wrong or the caller lacks access.
flora_app_get_sharing
ChatGPTRead how an app is shared: sharing_mode (restricted, view, edit), audience (link, org), passphrase_protected, and link_url — only for callers who may manage sharing. The link is a secret; do not repeat it beyond the user who asked.
flora_app_list
ChatGPTList a workspace's FLORA apps (single-file HTML apps published through FLORA), newest first: artifact_id (art_…), title, current_version, sharing_mode, the caller's access, and url. Metadata only; read the HTML with flora_app_get include_html.
flora_app_reserve_upload
ChatGPTReserve a signed URL for uploading one app HTML file (at most 2 MB) from a shell, for pages too large to send as html. Without artifact_id the upload creates an app in the workspace and counts against the free plan's cap of 2 live apps (flora_app_create upload_id); with artifact_id it publishes that app's next version and does not count as a new app (flora_app_update upload_id; needs manage access). Returns upload_id, the PUT url and headers, and instructions with the exact curl command. The upload is single-use, only for you, and expires unpublished after 24 hours. No shell to run curl? Don't reserve: send html, or edits to update.
flora_app_rollback
ChatGPTServe an earlier published version of an app again, by version number from flora_app_versions. The app's data is kept, so an older version must still read the data the newer one wrote. Requires manage access.
flora_app_share
ChatGPTShare an app by link and return it in link_url. The link is a secret: anyone it admits gets its access (audience "link": anyone holding it, signed-out guests included; "org": members of the app's organization), so hand it to the user and never post it elsewhere. access "edit" lets link holders write the app's data; "view" never downgrades an app already shared for edit — lower it with flora_app_update_sharing. A passphrase given here lands in the chat transcript. Requires manage access.
flora_app_update
ChatGPTChange an app's title, requested scopes or the projects its link viewers may read (project_ids), and with html publish the next version and make it current for every viewer. The app's data (app.db) is untouched; earlier versions stay available to flora_app_rollback. Only fields given change. For a new version, send either edits (old_string/new_string pairs applied in order to the current version's HTML; each old_string must match exactly one place, and on a miss nothing is published) or html (the whole new document). Prefer edits for changes smaller than the page: they don't resend it. Edits apply to the version current when this call arrives, so a publish by someone else since your read is kept as long as your old_strings still match. To publish only if nothing changed since you read it, pass base_version (the current_version you read); if another version is current by then, the call answers revision_conflict and publishes nothing: read the HTML again and redo your change. Read the current HTML with flora_app_get include_html first, and keep its collection names and document shapes so existing data still reads. Requires manage access. HTML rules, checked before publish: one complete document (<!doctype html><html>…</html>), at most 2 MB of raw HTML (not its JSON-escaped size). Write the document straight into html; drafting it in a local file first means writing it twice. Scripts inline, or <script src> / module imports over https from cdnjs.cloudflare.com, cdn.jsdelivr.net/npm or unpkg.com only, each naming an exact version (name@1.2.3; never @latest, a range, /gh/ or /combine/), and every <script src> carries integrity="sha…-…" crossorigin="anonymous". Leave integrity off a <script src> and FLORA fills it in from the CDN's own listing: cdnjs files, unpkg files, and jsDelivr files the package ships. jsDelivr minifies a missing .min.js and builds +esm on the fly, so those have no hash and are refused: pin a file the package ships. To set integrity yourself, cdnjs lists sha512 SRI at https://api.cdnjs.com/libraries/<name>/<version>?fields=sri and jsDelivr lists base64 sha256 at https://data.jsdelivr.com/v1/package/npm/<name>@<version>/flat (integrity="sha256-<hash>"). No import() of a computed URL and no scripts created from code. No iframes, embeds or objects of other pages (YouTube, Maps, Figma: link out instead). Images, video and audio load only from FLORA media (asset and output URLs from the API), data: and blob: — upload any other file with flora_create_asset and use its url. Checked at view time only (publish does not catch these, the page just breaks): no eval or new Function (libraries that compile templates at run time, such as Alpine.js or Vue's in-browser compiler, fail), no fetch to hosts other than FLORA, and no media URLs set from script outside FLORA media. The page runs in an opaque-origin sandbox: no cookies, localStorage, sessionStorage or IndexedDB, and requests carry Origin: null — persist state with app.db, never browser storage. Fonts and stylesheets load from Google Fonts or those CDNs; forms never submit anywhere (handle submit in script). Links open in a new tab. A content check also refuses pages that ask for passwords or payment details, imitate a sign-in or brand page, navigate the top window or hide code with eval, carry harmful content, or start generations without a viewer's click: the error lists each content_policy.* finding with what to change. Neither check runs the page: a successful publish means the page is allowed, not that it works. Syntax-check inline scripts before publishing when you can (node --check), and tell the user what you could not verify. Large page (over about 100 KB) and a shell to run curl? Write it to a local file, reserve an upload with flora_app_reserve_upload, PUT the file with the curl command it returns, then publish with upload_id instead of html: the page is written once, never pasted into a tool call, and checked exactly like html. Without a shell, keep sending html (or edits to update). After publishing, call flora_app_check to load the page in a headless…
flora_app_update_sharing
ChatGPTChange an app's link sharing explicitly. sharing_mode "restricted" unshares it and kills the link; reset_link: true replaces the link so every old one stops working. Unsharing, resetting the link, setting a passphrase, and narrowing audience from link to org also end every open link session. passphrase: null clears it. Only fields given change. The returned link_url is a secret. Requires manage access.
flora_app_versions
ChatGPTList every published version of an app, newest first, with its title, size, sha256 and which one viewers see (current). Pick a version here for flora_app_rollback.
flora_arrange_canvas
ChatGPTLay out nodes on a project canvas with FLORA's own layout engine instead of computing positions by hand. Two ways to place a set: omit layout for Tidy — the editor's own layout, which follows edges (sources left of the nodes they feed) and keeps group members inside their frame — or pass layout to put the named nodes in a row, a column, or a grid, in node_ids order, with cells sized to the measured/authored boxes or conservative unpainted estimates (a column as wide as its widest node, a row as tall as its tallest) and a gap between neighbours; the block starts at origin, or where the set already is when origin is omitted. Use a layout whenever the user asks for a row, a column, a grid, a comparison strip, or 'side by side' — never hand-compute a grid with flora_update_canvas_nodes. To align a new row with existing columns, origin.x is the painted left edge: for ordinary top-center anchors, origin.x = existing anchor x - node width/2 (a width-384 node anchored at x=0 starts painting at x=-192). Set gap to the existing column-anchor step minus node width; do not reuse an anchor x as origin.x. Already aligned explicit add positions need no further arrangement unless the layout must change. A layout needs node_ids that all sit at the top level or all inside the same group; members are laid out from the frame's padded corner and the frame is refit around all of its members (an explicit origin only grows it). Pass node_ids to arrange that subset, or all:true ONLY when the user asked to reorganize the whole canvas with Tidy, since that moves work they positioned by hand; with neither the call is rejected, and all:true takes no layout. On an older API, a subset is arranged in isolation and can overlap untouched work. Inspect overlaps after arranging; choose an origin clear of other work when needed. Unknown ids reject the whole call and nothing moves — pass ids exactly as flora_get_canvas, flora_list_canvas_nodes, or a flora_add_to_canvas / flora_attach_asset response reported them (api_asset_… node ids are valid); never predict an id and never pass a bare asset id (asset_…). Returns {arranged, moved, overlaps, bounds, revision}; moved:0 means the set was already laid out, bounds is the block's absolute box (place the next batch at origin y = bounds.y + bounds.height + gap), and a non-empty overlaps lists the short-id pairs that now collide — re-run with an origin clear of other work, all:true for a full Tidy reflow, or move nodes explicitly with flora_update_canvas_nodes. This API supports obstacle-safe row, column and grid layouts: when layout.origin is omitted, the entire block is translated clear of untouched work while preserving its order and spacing. Explicit origins can collide. For members of one field, omit origin to use its padded content corner. The exact frame anchor (both x and y equal the frame's graph position) is also accepted as that padded corner; other explicit origins remain literal and must be inside the padded area.
flora_attach_asset
ChatGPTPut an existing asset onto a project canvas as a node. This is how an asset created by flora_create_asset becomes visible in a project. The asset must report status "ready" — attaching a pending_upload or failed asset is rejected — so after flora_create_asset / flora_complete_asset, check the returned status or poll flora_get_asset until it is ready before calling this. The asset and the project must live in the same workspace.
flora_complete_asset
ChatGPTFinish a signed-url asset after its bytes have been uploaded. Returns the asset's final URL. To finish several, pass asset_ids instead (up to 25) — the asset_… ids one sources call reserved — in one call. It returns {assets}: every entry echoes its index and asset_id with ok, then either status ready or failed with failure_message, as a single completion reports, or an error when that asset could not be completed. One failed entry never stops the rest.
flora_create_asset
ChatGPTBring a file into a workspace. To bring in several files in one call, pass sources instead of source: an array of up to 25 entries, each {source, file_name, content_type, folder}, returning {assets} where every entry echoes its index and source and carries either the create response (an asset_… asset_id, and for "signed-url" entries its own upload descriptor and upload_page link) or {ok:false, error} — one failed entry never stops the rest. Prefer one sources call over several calls in parallel: every call counts against the workspace's shared API rate limit, and a sources call reserves all its signed-url entries in one request. workspace_id, project_id and folder apply to every entry. Pass source as a public HTTPS URL and FLORA fetches it server-side. Hosts that return 401/403/404 to FLORA's anonymous fetch (for example, hotlink-protected or login-gated hosts) must not be retried; download the file and use source="signed-url" instead. Pass source="signed-url" for a file that exists only on the user's machine: the response carries an upload_page link (valid 15 minutes) for the user to open in a browser, and an upload descriptor for clients with a shell. To use the descriptor, send a multipart POST to upload.url: one form field per upload.form_fields entry, sent verbatim, then the file bytes in the upload.file_field field, which must come last. Do not hardcode the endpoint or field names; they depend on the storage backend. Bytes upload only through the descriptor or upload_page — never from a code sandbox, which has no outbound network. Either way, finish the asset with flora_complete_asset (asset_ids finishes a sources batch in one call); if it reports the bytes missing after the user submitted or the link expired, call flora_create_asset again for a fresh reservation rather than reusing the old link. Only these content types upload: image/jpeg, image/png, image/webp, image/gif, image/avif, image/heic, image/heif, video/mp4, video/webm, video/quicktime, audio/mpeg, audio/wav, audio/ogg, audio/mp4, application/pdf (image/jpg, audio/x-m4a and application/x-pdf normalize onto the list). Anything else is rejected — rasterize SVG to PNG rather than retrying it, and keep 3D models on the model3d flows.
flora_create_custom_action
ChatGPTAdd one custom action node to a project canvas from source code you write, as a single API operation. The code is stored on the node, not run: it runs only when flora_run_canvas_action runs the node, in FLORA's sandbox (python, node) or the user's browser (browser). To place a prebuilt catalog action instead, use flora_add_action; to change an existing node's code, use flora_update_canvas_action rather than adding a second node. Declare the contract in comment lines at the top, one # @flora-x: value per line (// in JavaScript; a space instead of the colon also works): @flora-name: "Pixelate"; @flora-description: "Blocky pixels"; @flora-inputs: [{"name": "source", "type": "image"}]; @flora-outputs: [{"name": "out", "type": "image"}] (required; types image, video, audio, text, model3d; when you wire a source into the action with flora_add_to_canvas, the in of each connect is the declared input name, e.g. "source", never a type such as "image"); @flora-params: [{"key": "size", "label": "Block size", "type": "number", "default": 8, "min": 2, "max": 64}] (every entry needs key, label, type AND a default of the right type; types number, boolean, color, select with options [{label, value}], text, point2d, point3d, interval; visibleIf: [{key, equals}]). Runtime contract, Python: get_input(i) returns a dict {index, type, name, path} (a text input carries text instead of path); open media with Image.open(get_input(0)["path"]); read tunables with get_param("size", 8) using the declared camelCase keys; write each declared output with write_output("0-out.png", bytes_or_str) (outputs fill the declared slots in filename order, so prefix names to sort in declared order); Pillow, numpy, cv2, moviepy and ffmpeg are available; raise FloraUserError("message") for a user-facing error. JavaScript on the node runtime: getInput(i) gives {path|text}, getParam(key, default), writeOutput("out.png", buffer); sharp and canvas are available. JavaScript written as an ES module runs in the browser and, when it exports preview, previews live in the studio: export async function execute({ inputs, params, state }) returning {type: "image", dataUrl}, and export const preview = { mode: "wysiwyg", mount({ el, inputs, params, state, onState }) { return { update({ params, state }) {}, dispose() {} } } }; inputs are {type, dataUrl|text}; browser APIs only (Canvas2D/WebGL), no fetch. The flora-action-studio skill carries a complete tested template for each runtime. The workspace plan must include custom actions. flora_get_canvas lists the params of a custom node under their declared keys; the action reads and runs use their snake_case form; writes accept either.
flora_create_generations
ChatGPTStart 1–20 independent generations concurrently. SPENDS CREDITS for each successful submission unless quote=true: then return credit/cost estimates for these exact requests, including assumptions and expiry, without reserving credits or starting generations. Quote entries have no run_id and must not be polled. Pass generations as an array, even for one item; each item supplies project_id, type, and prompt; workspace_id may be omitted to bill the workspace project_id belongs to. Returns {generations: [...]} in input order, each with index and ok. Successful entries include run_id, canvas_url, and node_id; failed entries include error and status when available. Save every successful run_id and poll flora_list_generations with run_ids. Never retry the whole batch after a partial failure: successful submissions already spend credits, and a timeout may have started a run — inspect history before retrying uncertain submissions. Pass reference_node_ids to use existing canvas nodes as image or model3d inputs. Works with image-to-image models (type=image) and model3d models that accept image or model3d inputs; video and other models are rejected with invalid_parameters — to animate a canvas image, add a video node wired to it with flora_add_to_canvas and start it with flora_run_canvas_nodes using the short id from the created map. Text-to-image ids (t2i-*) with references route to the same model's image-to-image shape when one exists; otherwise they are rejected with invalid_parameters. Media input field names (image_url vs image_urls, model_url) come from flora_list_models — use those names in params, or pass reference_node_ids instead of pasting URLs. Omit model to pick a default: image references use image-to-image or image-to-model3d. Model3D remesh/retexture (model3d sources) requires an explicit model from flora_list_models that declares model_url. Never build project URLs from ids; use canvas_url.
flora_create_project
ChatGPTCreate an empty project canvas in a workspace. Pass folder to file it under a shared project folder with that name — the folder is created when it does not exist yet; list names with flora_list_folders first.
flora_create_skill
ChatGPTCreate a shared skill in a workspace (ws_…) from flora_list_workspaces or current_workspace_id. The workspace needs the paid workspace-skills feature and write access; on a 402/403 refusal, ask for access or use a workspace that grants it. The content is the instruction body agents follow. Returns the slug flora_discover_skills retrieves it by. Personal user skills are not writable through this API.
flora_discover_skills
ChatGPTDiscover reusable FLORA skills. Call without a name to list skills — the FLORA catalog, plus your own user skills (always included, no workspace_id needed), plus shared skills when you pass a workspace_id from flora_list_workspaces (or its current_workspace_id). Pass a name to retrieve instructions; include workspace_id for a workspace skill. If workspace access is refused (402/403), omit workspace_id or ask for access to the paid workspace-skills feature.
flora_get_action
ChatGPTRead one prebuilt catalog action's definition: its name, description, declared inputs and outputs, and the params it accepts with their types and defaults. Read-only: it runs nothing. An action is a deterministic media or text transform (crop, resize, rotate, colour-grade, stitch or split video, split or replace text, …): one of FLORA's 42 prebuilt catalog actions, or a custom action a user wrote as code on a canvas. Actions spend no credits, but the workspace plan must include them.
flora_get_asset
ChatGPTGet one asset's metadata, including failure_message when its upload did not finish. flora_list_assets covers the rest. Pass asset_ids instead (up to 100) to resolve a batch of ids to their URLs in one call — the asset_ids a generation's inputs report — each entry echoes the id with its url or not_found:true.
flora_get_canvas
ChatGPTRead a project canvas in full: every node with its short id (n7), UUID, type, label, group (direct parent field short id, null for top-level nodes; omitted on older APIs), prompt, model, params, position (the anchor: top-center of the box for every type but group, which anchors top-left), size (the measured or authored box, or a conservative estimate until painted), generation status and current output, the edges between them, and an opaque revision that changes whenever anything here does. Idle nodes (added but never run) appear here; flora_list_canvas_nodes lists only media outputs. The short ids are what every canvas write accepts. A timeline node reports only a document summary: read the whole document with flora_get_canvas_node_document. A notes node carries its whole body in text.
flora_get_canvas_node_document
ChatGPTBefore reading or editing a Deck, call flora_discover_skills with name="flora-deck-editor" and follow its workflow. Read the full authored content of a document-bearing canvas node — a timeline's tracks, items and assets, a deck's slides and layers, or a note's whole text body — with its revision. For a timeline or deck, flora_get_canvas carries only a summary. To edit: read the document here, change it, and send the whole document back with flora_update_canvas_node_document, passing base_revision set to the revision read here; a stale base_revision is rejected with revision_conflict instead of overwriting another edit. Deck updates require base_revision; change only the requested slides/layers and preserve the others, including their IDs and source bindings. Deck revision checks reject observed stale reads but do not serialize simultaneous collaborators. A node that carries no document is rejected — use flora_get_canvas for its prompt, model and params; use flora_list_canvas_nodes for media outputs, including Model3D files; a timeline with no document yet returns not_found (write one with base_revision 0). A note reads as {kind:"notes", text} at revision 0 and is edited with flora_update_canvas_nodes carrying text, not with flora_update_canvas_node_document. For a deck node, pass slide to read one slide — its frame, guides and layers — instead of the whole document, and slide plus layer to read one layer; both return the revision a scoped write needs.
flora_get_lora
ChatGPTRead a saved LoRA Style's readiness, base_model and saved trigger metadata in a workspace. Pass the style_id from flora_train_lora. When ready, pass this ID as params.lora_id (not params.style_id) in an item of flora_create_generations with a compatible model. Missing, deleted and inaccessible Styles return 404; poll the training run_id with flora_list_generations using run_ids to diagnose a failed training.
flora_get_project
ChatGPTGet one project's metadata. Pass project_id with the prj_ prefix from flora_list_projects or flora_create_project; an API-issued canvas URL's /projects/<id> segment becomes prj_<id>, while a bare ID is not accepted.
flora_get_project_sharing
ChatGPTRead how a project is shared: link sharing mode, the active share link (only when the user may manage sharing), owner, and members.
flora_get_technique
ChatGPTGet one technique's declared inputs and outputs. Call this before flora_run_technique: the input ids it returns are the keys that tool's inputs map expects.
flora_get_usage
ChatGPTRead balance and spend in USD, not credits, for one workspace (workspace_id, ws_…) or across an organization (organization_id, org_…); pass exactly one. Unsure which workspace? Call flora_list_workspaces first: it returns both ids, and current_workspace_id when the user is already in one. Workspace: available_cost is what can be spent now. It is current rather than limited to the date range, does not reflect workspace spending caps, and does not guarantee a run will be admitted. What it covers depends on the caller, who may see only their own balance, and workspaces of one organization may share a pool, so never sum it across workspaces. balance_scope workspace (billing permission on a plan with usage reporting): the pool's balance, and spend carries the workspace's total_cost, classified_runs and runs_by_category for the range. balance_scope caller (anyone else, including billing admins on a plan without usage reporting): only the caller's own allowance, plus member_limit when a spending limit binds them, and spend is unavailable with reason entitlement_missing (the plan lacks usage reporting) or permission_missing (the caller lacks billing permission). Relay that reason; it never means zero spend. summary_unavailable means the totals could not be computed; a shorter range may help. classified_runs counts only runs with a known output type; unclassified spend still counts in total_cost. Organization: spend only, no balance. It returns total_cost, total_runs and runs_by_category across all its workspaces, and group_by adds by_workspace, by_model or by_day. It needs billing permission in an organization with multiple workspaces enabled. Dates are inclusive UTC days (YYYY-MM-DD) and default to the 30 days ending today; a workspace range spans at most 31 days and ends no later than today, an organization range at most 366 days. An API key needs billing permission on the workspace; other workspaces and organizations return 403.
flora_list_assets
ChatGPTList assets in a workspace or project.
flora_list_canvas_nodes
ChatGPTList a project canvas's media nodes with their asset URLs. Idle generation nodes (added but never run) do not appear here — use flora_get_canvas to see them and the graph structure.
flora_list_folders
ChatGPTList a workspace's shared project folders — folder_id (fld_…), name and project count, in workspace order; private folders never appear. Pass a folder name as flora_create_project's folder to file new projects into it.
flora_list_generations
ChatGPTRead specific generation runs or list history. Given run IDs, pass run_ids (an array even for one run); never substitute history or another run's result. Regular run IDs need no workspace or project lookup. For technique runs, also pass technique_id; flora_list_technique_runs lists history, not an exact run lookup. Read all IDs of a batch in one call, up to 20. Reading does not block: runs take tens of seconds, so wait between polls of the same batch — at least 15 seconds, and about 2 seconds per id for larger batches (40 seconds for 20) — because every id in run_ids is one API request against the workspace's per-minute rate limit, and faster polling returns status 429 error entries. Repeated or overlapping reads inside the poll interval receive a cooldown error with retry_after_seconds; no run payload is cached, so every returned run is freshly authorized by the API. A batch where every id is rate-limited or cooling down fails the whole call with retry_after_seconds. run_ids returns {runs}, with a separate error entry (ok:false, error, and status when the API answered) for each unreadable ID. Only omit run_ids when the user wants history; that returns the API page under generations, newest first, with cost and outputs. Pass include_inputs on a history read to also get each run's submitted prompt and input references. Past the tool-result size budget, long text fields come back as previews flagged inputs.truncated — narrow the page or read full text through the API (GET /generations?include_inputs=true) or SDK directly.
flora_list_lora_trainers
ChatGPTDiscover available LoRA trainer families, supported training parameters and effective web defaults, image-count limits/formats, and compatible inference model IDs with strength defaults/ranges. Call before flora_train_lora so base_model and trainer_params come from the live catalog. The resulting Style is attached to inference with params.lora_id. Defaults describe a dataset without manual labels; supplying labels selects manual captioning unless an explicit automatic mode conflicts.
flora_list_models
ChatGPTList the generation models available to this account. When FLORA curates featured models they come first under featured, grouped by type (featured models are not repeated in models, and limit caps the total across both). Returns a summary per model with its capabilities, such as text-to-image or image-to-video; pass model_id to get one model's full parameter list for flora_create_generations.
flora_list_projects
ChatGPTList projects in a workspace, most recently active first. workspace_id may be omitted when the caller has a single workspace (or the connection is signed into one). Without visibility, the caller's own projects; visibility narrows to their private ones or widens to every member's shared canvases. Project ids (prj_…) come from this response or an API-issued canvas URL; never guess one.
flora_list_technique_runs
ChatGPTList past technique runs with their status, cost, and outputs. Also the way to find technique ids from work already done in a workspace.
flora_list_techniques
ChatGPTList saved techniques (reusable multi-step workflows) with their declared inputs, outputs, and run cost.
flora_list_tools
ChatGPTList the tools available to the model on this FLORA connection, with a short purpose and safety hints for each. These purposes are abbreviated previews, not calling instructions. Before calling a listed tool, read its full registered description and input schema from your host's tools/list, including payment, retry and permission constraints.
flora_list_workspaces
ChatGPTList the FLORA workspaces this account can use. For an existing project, use its own workspace: canvas tools with optional workspace_id resolve it from project_id, so no separate workspace lookup is needed. For operations that require choosing a workspace, use current_workspace_id when returned; it is the workspace the user is already in. Otherwise, if multiple workspaces come back, name them and ask which to bill — workspaces differ in plan and entitlements. Pair any explicit workspace_id with the project's own workspace; a mismatch is rejected.
flora_mention_projects
ChatGPTSearch FLORA projects for composer @-mentions. Called by the host as the user types, not by the model.
flora_open_action_studio
ChatGPTOpen the FLORA action studio on one prebuilt catalog action and the inline inputs you supply, without running it, so the user can tune its parameters first. An action is a deterministic media or text transform (crop, resize, rotate, colour-grade, stitch or split video, split or replace text, …): one of FLORA's 42 prebuilt catalog actions, or a custom action a user wrote as code on a canvas. Actions spend no credits, but the workspace plan must include them. Read-only: it starts no run, writes nothing and spends nothing. To build the view it reads the action's definition. The user adjusts the parameters there and clicks Apply, which calls flora_run_action once with the chosen settings; once that run starts the view reads its status with flora_list_generations until it finishes, and Save to canvas adds the outputs with flora_add_to_canvas. Do not start a run yourself and do not poll: when the applied run finishes, the studio hands you its run id, status, outputs and final params. Hosts without MCP Apps cannot show the studio; run the action with flora_run_action there instead.
flora_open_canvas_action_studio
ChatGPTOpen the FLORA action studio on one action node that already sits on a project canvas, prebuilt or custom, without running it, so the user can tune its parameters first. The studio shows the node's stored parameter values and wired inputs. Read-only: it starts no run, writes nothing and spends nothing. To build the view it reads the action's definition. The user adjusts the parameters there and clicks Apply, which calls flora_run_canvas_action once with the chosen settings; once that run starts the view reads its status with flora_list_generations until it finishes, and Save to canvas adds the outputs with flora_add_to_canvas. Do not start a run yourself and do not poll: when the applied run finishes, the studio hands you its run id, status, outputs and final params. Hosts without MCP Apps cannot show the studio; run the action with flora_run_canvas_action there instead.
flora_open_project
ChatGPTCreate a single-use sign-in link that opens one project canvas in a browser, signed in as the user, for session_hours. One API operation; it changes nothing in the project and returns url, canvas_url and expires_at. Open url in a browser tab you control and navigate within that tab rather than reloading it; the canvas then behaves as it does for the user. Only useful in hosts that can open and operate a browser tab (Claude Code Desktop, Cowork, or similar); elsewhere read the project with flora_get_project and flora_get_canvas, and change it with the canvas tools, instead. The link works once and acts as the user — never share it or put it in a reply. A 404 means the project id is wrong or the caller lacks access — report it, do not retry.
flora_organize_canvas_fields
ChatGPTOrganize existing nodes into named fields without recreating nodes or changing their content or edges. Pass fields with labels and existing node_ids from flora_get_canvas (up to 200 requested members total). Prefer this tool for sorting work into Concepts/Finals or other fields: it validates all members first, reuses a unique matching top-level field label or creates an empty field, moves the existing nodes, grids each field's members, then separates the fitted field frames in a row clear of untouched work. Existing members of reused fields are preserved and reflowed. If existing positions must stay fixed, add or arrange only the new IDs with the dedicated add/arrange tools instead. Duplicate member IDs, ambiguous labels, nested frames, notes, labels and groups as members reject before writes. This is a multi-request workflow, not an atomic transaction: if interrupted, read the canvas and retry with the same field labels and member IDs to reuse committed frames. No explicit coordinates are accepted; use flora_update_canvas_nodes and flora_arrange_canvas for precise placement. Does not run generations.
flora_project_tray
ChatGPTOpen the FLORA project tray beside this conversation. Launched from the conversation's tabs, not by the model.
flora_projects
ChatGPTOpen the FLORA projects browser. Launched from the sidebar, not by the model.
flora_remove_from_canvas
ChatGPTDelete nodes from a project canvas. Every edge touching a deleted node goes with it, and deleting a group deletes its members too; the response's removed count includes them. Deletion is immediate and cannot be undone through the API, so pass only the nodes the user asked to remove — to clear a node's content or wiring instead, edit it with flora_update_canvas_nodes. Nodes are addressed by the short id (n7) or UUID flora_get_canvas reports; an unknown id rejects the whole call with ref_not_found and nothing is deleted.
flora_rename_project
ChatGPTRename a project: pass project_id (prj_…) and the new name. The API allows up to 120 characters, trims surrounding whitespace, and rejects an empty result. Projects managed by a Generation Table or backing a Production cannot be renamed here — rename them from the owning surface.
flora_run_action
ChatGPTRun a prebuilt action headlessly on inputs you supply inline. Credit-free. This does NOT touch the canvas — nothing appears in the project, and outputs come back from flora_get_run. project_id only scopes authorization and generation history. To produce a canvas node, use flora_add_action then flora_run_canvas_action. Returns canvas_url; give the user that link rather than building one from an id.
flora_run_canvas_action
ChatGPTRun an action node that already sits on a canvas, taking its inputs from the nodes wired into it and writing outputs back to canvas result nodes. Credit-free. Place the node first with flora_add_action, and connect its inputs — an action with required inputs and no incoming edges fails. Returns canvas_url; give the user that link rather than building one from an id.
flora_run_canvas_nodes
ChatGPTRun generation nodes (image, video, text, audio, model3d) and timeline (video editor) nodes that already sit on a project canvas. Generation nodes run using the model, prompt, parameters and wired upstream inputs each node carries — configure the node first with flora_add_to_canvas or flora_update_canvas_nodes. A timeline node renders its document through the video editor render pipeline instead: it needs a document (written via flora_add_to_canvas, flora_update_canvas_node_document, or the editor) and spends timeline render usage rather than generation credits, so its started entry carries no model or cost estimate. SPENDS CREDITS immediately, with no confirmation step; quote a cost to the user first. Returns one entry per node_id: started entries carry a run_id to poll with flora_list_generations (generations) or GET /runs/{runId} (timeline renders report progress and the finished video there), skipped entries carry a machine-readable reason (node_not_found, node_not_executable, no_model_configured, generation_already_running, timeline_no_document, timeline_not_entitled, …) and never fail the rest of the batch. Connected nodes run in dependency order, so a whole chain can be started in one call. For action nodes use flora_run_canvas_action instead.
flora_run_technique
ChatGPTRun a saved technique. SPENDS CREDITS. inputs is a map keyed by the input ids from flora_get_technique, valued with text or asset URLs; each value is sent as the type the technique declares for that input. URL-typed (media) inputs must use FLORA-hosted or allowlisted media URLs. Upload external media first with flora_create_asset and pass its returned url. Returns a run_id — poll it with flora_list_generations, passing this same technique_id. In MCP Apps hosts the call opens the FLORA action studio, where the user edits the technique's inputs and clicks Apply to run it (each Apply bills run_cost); pass open_only: true to open it without running anything. The studio waits for the run and hands you its run id, status, outputs and final inputs.
flora_search_actions
ChatGPTSearch the prebuilt action registry (deterministic media/text transforms — crop, stitch, split, colour-grade). Actions are credit-free.
flora_share_project
ChatGPTShare a project by link, the way the canvas Share tab does, and return the link. Anyone who has the link gets its access, so hand it to the user rather than posting it elsewhere. access: "edit" may be refused on the workspace plan (paid_plan_required); access: "view" never downgrades a project already shared for editing (its view link is returned). A passphrase given here lands in the chat transcript.
flora_train_lora
ChatGPTTrain and save a LoRA using the same image preparation, captions, defaults, billing and Style lifecycle as the FLORA web Train dialog. SPENDS USAGE. Upload source images with flora_create_asset first, then pass their FLORA URLs. Choose the base_model family (for example flux-2 or krea-2). Persist one lowercase UUID client_token before submitting; reuse it with the same inputs if the response is lost. Returns style_id and run_id. Poll flora_list_generations with run_ids: [run_id] and check flora_get_lora readiness, then use params.lora_id with flora_create_generations. Do not train by passing a trainer model to flora_create_generations: that bypasses the saved Style lifecycle.
flora_update_canvas_action
ChatGPTChange one existing action node in place, as a single API operation; only the fields given change. Any action node takes label and params. A custom node also takes code, language and runtime, and new code overwrites the previous code, which is why the tool is marked destructive. The node keeps its id and wiring, and param values the new code still declares survive. Nothing runs: run it afterwards with flora_run_canvas_action. Fix a broken custom action this way, never by adding a second node. New code follows the same @flora-* contract and runtime helpers as flora_create_custom_action. For writing or fixing custom action code, the flora-action-studio skill (flora_discover_skills with name="flora-action-studio") carries tested templates.
flora_update_canvas_node_document
ChatGPTBefore editing a Deck, call flora_discover_skills with name="flora-deck-editor" and follow its workflow. Replace the authored document of a document-bearing canvas node — a timeline's whole document ({kind:"timeline", schema_version:1, fps, composition_width, composition_height, tracks, items, assets}) or a deck's whole document ({kind:"deck", schema_version:1, slides}), snake_case, not a patch. Read it first with flora_get_canvas_node_document, change only what was asked and preserve the rest (a deck's other slides and layers keep their IDs and source bindings), and send the entire document back with base_revision set to the revision you read (0 for a timeline that has no document yet). A stale base_revision is rejected with revision_conflict and nothing is written: read again and reapply the change. The document is validated with the workspace's limits before anything is written, and a rejection names the field by JSON pointer. Writing a document does not render it: a timeline renders through flora_run_canvas_nodes; a deck has no render or PDF export on this server. For a deck node, pass commands instead of document to edit in place — slide ops (add_slide, duplicate_slide, remove_slide, move_slide, set_slide_hidden, set_slide_background, set_guides) and layer ops (add_layers, update_layers, update_layer_geometry, remove_layers, reorder_layers) naming slides and layers by id — without resending the whole document. commands and document are mutually exclusive; a rejected command fails the call naming its index. The flora-deck-editor skill carries the layer vocabulary.
flora_update_canvas_nodes
ChatGPTEdit nodes and edges that already sit on a project canvas, in place, keeping their ids, outputs and other wiring. One call is one canvas changeset API operation with two kinds of write: update overwrites the fields it names on existing nodes, and disconnect removes edges. It never adds or deletes nodes, never runs a generation and spends no credits. Each update names one existing node by the short id (n7) or UUID flora_get_canvas reports and replaces only the fields it carries: label, prompt, model, params (merged key by key into the stored parameters — a named key is overwritten, omitted keys survive), position (absolute canvas coordinates; move a node by writing the x/y you want, reading its current position and neighbours from flora_get_canvas) and, for a notes node, text (its whole body), size, or fit_text:true to show the whole body without scrolling; flora_get_canvas reports the resulting size. One update per node; an unknown id rejects the whole call with ref_not_found and nothing changes. Each disconnect removes the edge between two nodes ({from, to, in?}; omit in to drop every edge between the pair); naming an edge that does not exist rejects the whole call with ref_not_found, so read the edges from flora_get_canvas first. Editing a generation node does NOT run it: its current output stays until flora_run_canvas_nodes runs it again, and params are validated against the model's schema before anything is written. Outside this tool: add nodes or edges with flora_add_to_canvas, delete nodes with flora_remove_from_canvas, replace a timeline or deck document with flora_update_canvas_node_document, and lay many nodes out at once with flora_arrange_canvas rather than computing every position by hand. The response reports applied counts, a revision and warnings — an update that matched the canvas already is reported there rather than failing. Organize existing work by moving nodes, never by adding copies. Create a new empty group first, then update the existing IDs with group. Arrange each field's members, then the field frames themselves with flora_arrange_canvas and read back to verify membership and spacing. Move a node into a group frame with group — a group's short id or UUID, or null to ungroup the node to the top level; the node keeps its canvas spot and the frame it joins grows to wrap it. Swap a static image, video or audio node's media in place with content_url (a file copied onto Flora's CDN) or asset_id (a library asset, referenced not copied); the node keeps its id, edges, group and label. Pass content_url or asset_id, never both, and not alongside prompt, model, params, text, size or fit_text.
flora_update_project_sharing
ChatGPTChange a project's link sharing explicitly. sharing_mode: "restricted" unshares it (every link stops resolving) and view revokes an edit link; edit opens it for editing (may be refused on the plan: paid_plan_required). passphrase: null clears the passphrase. Only fields given change.
flora_view_model3d
ChatGPTOpen an interactive 3D viewer for a run from flora_list_generations. Read-only and credit-free: orbit, pan, zoom, reset, inspect metadata, or open the GLB. Supply technique_id for technique runs. Returns asset_id and GLB links for chaining without geometry bytes, plus up to three provider preview images when available. The model can evaluate only those image blocks, not the user's interactive view; no previews means visual quality is unknown. Pending runs can be refreshed. Never inline a GLB.