--- title: "Create, move, resize or delete many items in one draw" method: POST path: "/boards/{boardId}/items:batch" tags: ["Items"] --- # Create, move, resize or delete many items in one draw `POST /boards/{boardId}/items:batch` ## Request - Base URL: `https://api.mockflow.com/v1` - URL: `https://api.mockflow.com/v1/boards/{boardId}/items:batch` - Auth: HTTP bearer Up to 100 operations, validated together before anything is drawn, then drawn as one action. Updates in a batch change position and size; replacing an item's data is PATCH /items/{itemId}. The Job's `result.itemIds` lists the created items, `updated` and `deleted` the others. ## Headers - `Idempotency-Key` string ## Request body - object - `callbackUrl` string, uri: Optional. When the job this request starts finishes or fails, a short body is POSTed here once: `{ eventId, status, boardId, boardUrl, imageUrl }`, where status is `succeeded` or `failed` and imageUrl is a picture of what the job drew, or null. Signed with the workspace's callback secret (GET /webhooks/callback-secret). https to a public host. The full job is on GET /jobs/{jobId}. - `operations` union[], required - union - object - `op` 'create', required - `item` ItemCreate, required - `callbackUrl` string, uri: Optional. When the job this request starts finishes or fails, a short body is POSTed here once: `{ eventId, status, boardId, boardUrl, imageUrl }`, where status is `succeeded` or `failed` and imageUrl is a picture of what the job drew, or null. Signed with the workspace's callback secret (GET /webhooks/callback-secret). https to a public host. The full job is on GET /jobs/{jobId}. - `type` 'artifact' | 'audio' | 'calendar' | 'chart' | 'checklist' | 'cloud_architecture' | 'code_block' | 'comment' | 'connector' | 'customer_journey' | 'data_simulator' | 'database_diagram' | 'design' | 'floorplan' | 'flowchart' | 'gantt' | 'image' | 'kanban' | 'knowledge_graph' | 'map' | 'map_regions' | 'markdown' | 'mindmap' | 'model_3d' | 'mood_frame' | 'poll' | 'prototype' | 'reaction' | 'section' | 'shape' | 'spinning_wheel' | 'spreadsheet' | 'sticky_note' | 'storyboard' | 'strategy_map' | 'swimlane' | 'table' | 'text' | 'timeline' | 'tree_diagram' | 'upvote_ideas' | 'video' | 'whiteboard' | 'whiteboard_frame' | 'wireframe', required: Item types, generated from the MockFlow component registry. Primitive types are drawn by the editor; frame types are rich components whose `data` schema is the same one the MCP `render_*` tool accepts. - `position` Point - `x` number, required - `y` number, required - `size` Size - `width` number - `height` number - `data` union, required: Selected by the sibling `type`. One schema per item type, generated from the component registry. - ArtifactData: Turn a small collaborative widget YOU write into a live, runnable MockFlow IdeaBoard tile, and get back the board URL. Use this when the user wants a working tool, game, poll, wheel, timer or quiz they will interact WITH on the board: decision tools (spinning wheel, dice, random picker, live poll), meeting tools (planning poker, countdown, standup order), learning tools (flashcards, a live quiz), turn-based games, small calculators. NOT for wireframes or prototypes of an app design (use render_wireframe / render_prototypelite) and NOT for what-if data models (use render_datasimulator). It is NOT a full application: one screen, one job, no routing, no accounts. No AI credits are used: you author the whole tile. Also available as the MCP tool `render_artifact`. The same payload works through either surface. - … - AudioData: Generate sound to listen to - music, a sound effect, speech, voiceover, narration or a jingle - and place it on the board as an audio player component. Also available as the MCP tool `render_audio`. The same payload works through either surface. - … - CalendarData: Create a calendar with events for schedules, appointments, holidays, and event planning. Also available as the MCP tool `render_calendar`. The same payload works through either surface. - … - ChartData: Create charts including pie, bar, line, area, scatter, bubble, and radar charts. Only for plotting VALUES: a "chart" that plots nothing and instead shows how people or parts relate (org chart, reporting structure, hierarchy tree) is a diagram — use render_flowchart. Also available as the MCP tool `render_chart`. The same payload works through either surface. - … - ChecklistData: Create a checklist / to-do list of actionable tasks with checkboxes. Use this for task lists, action items, checklists, shopping lists, project task breakdowns, or any content organizing things that need to be completed. For status-column task boards use render_kanban; for scheduled tasks with durations use render_gantt. Also available as the MCP tool `render_checklist`. The same payload works through either surface. - … - CloudArchitectureData: Create cloud/software system architecture diagrams — backend, microservices, deployment, infrastructure, integration or network architecture — for AWS, Azure, GCP, Kubernetes, SAP, or generic systems (use "aws" icons when no provider is named). ONLY for technical software/cloud/network diagrams — NOT for physical buildings, construction, or real-world/building architecture. Also available as the MCP tool `render_cloudarchitecture`. The same payload works through either surface. - … - CodeBlockData: Create a syntax-highlighted code block from a snippet of source code. Also available as the MCP tool `render_codeblock`. The same payload works through either surface. - … - CommentData: A comment pin. On create, `message` starts the thread. On read, `comments` is the thread: the first entry is the comment, the rest are replies. - … - ConnectorData - … - CustomerJourneyData: Create customer journey maps with stages, activities, and satisfaction metrics. Also available as the MCP tool `render_customerjourney`. The same payload works through either surface. - … - DataSimulatorData: Create a live, parameterized what-if simulation: a runnable model the user drives with sliders and play/scrub controls, every output recomputing as they move. Use this for business models (growth, churn, revenue, unit economics), funnels with conversion rates, forecasts and projections, capacity/queue models, epidemic/population dynamics, financial models (compound interest, runway), sensitivity/what-if analysis, and data infographics (metric cards, charts, gauges and funnels composed around one topic). Use this INSTEAD of a chart or table whenever the point is to explore how outcomes CHANGE as the inputs change over time. Also available as the MCP tool `render_datasimulator`. The same payload works through either surface. - … - DatabaseDiagramData: Create database diagrams (ER diagrams) showing tables, columns, primary keys, foreign keys, and relationships. Also available as the MCP tool `render_database`. The same payload works through either surface. - … - DesignData: Create an editable graphic DESIGN (render_design) in a MockFlow IdeaBoard design frame: posters, flyers, banners, social posts and ads (Instagram, Facebook, LinkedIn, X, Pinterest, TikTok), YouTube thumbnails, menus, infographics, memes, podcast/album/book covers, product listing images, business cards, invitations, brand layouts. You write ONE page of positioned text, shapes, pictures and lines as JSON, never HTML or CSS; MockFlow draws it and the user edits every element afterwards. For UI screens use render_wireframe; for a single picture use render_image. Also available as the MCP tool `render_design`. The same payload works through either surface. - … - FloorplanData: Create a FLOOR PLAN — a top-down spatial layout of a building or space: rooms (axis-aligned rectangles sharing walls), doors, windows, furniture stamps from a fixed catalog, and short text labels, all on a grid. Also available as the MCP tool `render_floorplan`. The same payload works through either surface. - … - FlowchartData: Create diagrams including: Flowcharts, Sketchy Diagrams, 3D Isometric Diagrams, Bio/Medical Diagrams, Circuit Diagrams, P&ID Diagrams, UML Diagrams, Sketchy UML, Sequence Diagrams, Cloud Isometric Diagrams, Web Layout Diagrams, and Mobile Layout Diagrams. NOT for org charts, sitemaps, family trees or other single-rooted hierarchy trees — use render_treediagram; NOT for cross-functional/swimlane (lane-per-role) diagrams — use render_swimlane; NOT for AWS/Azure/GCP cloud infrastructure — use render_cloudarchitecture; NOT for database/ER schemas — use render_database. Also available as the MCP tool `render_flowchart`. The same payload works through either surface. - … - GanttData: Create a Gantt chart with project phases and tasks for project planning, scheduling, and milestone tracking. Use this for task management with durations, progress, assignees, and grouped phases. For simple chronological event visualization (history, milestones, biography events), use render_timeline instead. Also available as the MCP tool `render_gantt`. The same payload works through either surface. - … - ImageData: Generate a standalone picture - an illustration, photo, artwork, icon or logo - and place it on the board as an image component. Use this whenever the user asks for an image/picture/photo/illustration of something. Also available as the MCP tool `render_image`. The same payload works through either surface. - … - KanbanData: Create a Kanban board with columns and task cards for project management, sprint planning, and task tracking. Also available as the MCP tool `render_kanban`. The same payload works through either surface. - … - KnowledgeGraphData: Create a knowledge graph (bubble network) showing how concepts relate to each other, like an Obsidian graph view. Also available as the MCP tool `render_knowledgegraph`. The same payload works through either surface. - … - MapData: Create maps with location markers (pins) for plotting SPECIFIC INDIVIDUAL PLACES on a real-world map. Also available as the MCP tool `render_map`. The same payload works through either surface. - … - MapRegionsData: Create a CHOROPLETH map — a real-world map where whole geographic AREAS (countries, states, provinces, continents, world regions) are FILLED with color to encode a value or category. Also available as the MCP tool `render_mapregions`. The same payload works through either surface. - … - MarkdownData: Create markdown documents with headings, paragraphs, lists, and AI-generated images. Also available as the MCP tool `render_markdown`. The same payload works through either surface. - … - MindmapData: Create a mindmap for brainstorming, topic exploration, and hierarchical idea organization. Also available as the MCP tool `render_mindmap`. The same payload works through either surface. - … - Model3dData: Generate an actual 3D model - an object, character, prop or scene mesh (GLB/GLTF) - and place it on the board as a 3D model viewer component. Also available as the MCP tool `render_3dmodel`. The same payload works through either surface. - … - MoodFrameData: Create a mood/inspiration board inside a MockFlow IdeaBoard mood frame: color palette swatches, typography specimens, keyword/mood text tiles, and photographic image tiles. NOT a way to make a picture: this composes a whole board of swatches, type and tiles, so "an image/photo of X" is render_image, not this tool, even though a moodboard can contain imagery. Also available as the MCP tool `render_moodframe`. The same payload works through either surface. - … - PollData: Create a poll / voting question where users pick from predefined options. Use this for polls, surveys, opinion votes, multiple-choice questions, audience polls, feedback forms, or quick votes. For collecting AND upvoting open-ended ideas use render_upvoteideas; for a random picker use render_spinningwheel. Also available as the MCP tool `render_poll`. The same payload works through either surface. - … - PrototypeData: Turn a self-contained interactive prototype YOU generate into an editable MockFlow IdeaBoard component, and get back the board URL. Also available as the MCP tool `render_prototypelite`. The same payload works through either surface. - … - ReactionData - … - SectionData - … - ShapeData - … - SpinningWheelData: Create a spinning wheel / random picker with labeled segments. Use this for prize wheels, decision wheels, random selectors, wheel-of-fortune games, icebreakers, or any wheel-based random choice tool. For structured voting use render_poll; for upvotable ideas use render_upvoteideas. Also available as the MCP tool `render_spinningwheel`. The same payload works through either surface. - … - SpreadsheetData: Create spreadsheets with cell data, formulas, and formatting. Also available as the MCP tool `render_spreadsheet`. The same payload works through either surface. - … - StickyNoteData - … - StoryboardData: Create a film/video storyboard with scenes and frames for visualizing stories, movie sequences, commercials, and video content. Also available as the MCP tool `render_storyboard`. The same payload works through either surface. - … - StrategyMapData: Create a STRATEGY MAP — a plan DRAWN ON a real-world map: zones, coverage circles, route arrows, markers and short text notes over real geography. Also available as the MCP tool `render_strategymap`. The same payload works through either surface. - … - SwimlaneData: Create swimlane (cross-functional) diagrams with horizontal rows representing actors, departments, or roles, and flowchart nodes positioned within them. Also available as the MCP tool `render_swimlane`. The same payload works through either surface. - … - TableData: Create a board table of typed records: rows and columns where each column has a type (text, number, single/multi select with coloured options, date, checkbox, URL, media links, votes, sticky-note cells). Use it for rosters, comparison tables, inventories, directories, idea lists the team votes on, retro columns and simple 2x2 or SWOT grids that collect sticky notes. NOT for spreadsheets needing formulas or calculations (use render_spreadsheet); NOT for tasks moving through stages (use render_kanban); NOT for elaborate strategy canvases like RACI, BCG, Ansoff or segmentation frameworks (use render_whiteboard). Also available as the MCP tool `render_table`. The same payload works through either surface. - … - TextData - … - TimelineData: Create a timeline for visualizing chronological events, milestones, history, evolution, or sequential stages. Use this for simple chronological visualization of events or milestones WITHOUT task management. For project plans with tasks, durations, progress, and assignees, use render_gantt instead. Also available as the MCP tool `render_timeline`. The same payload works through either surface. - … - TreeDiagramData: Create a top-down hierarchy tree diagram. Four categories: "sitemap" (website page hierarchy), "orgchart" (reporting structure of people/teams), "tree" (generic hierarchy: taxonomy, family tree, folder structure), "wbs" (project work breakdown structure). Also available as the MCP tool `render_treediagram`. The same payload works through either surface. - … - UpvoteIdeasData: Create an idea board where users submit and upvote ideas. Use this for idea lists, feature request boards, suggestion boxes, brainstorm lists, feedback boards, or any content where users vote up/down open-ended ideas or suggestions. For fixed multiple-choice voting use render_poll; for a random picker use render_spinningwheel. Also available as the MCP tool `render_upvoteideas`. The same payload works through either surface. - … - VideoData: Generate a short video clip - animation, motion graphics, cinematic or any moving content - and place it on the board as a video player component. Also available as the MCP tool `render_video`. The same payload works through either surface. - … - WhiteboardData: Create whiteboards for freeform brainstorming AND structured strategy work: sticky notes and sections, named frameworks (SWOT, SCAMPER, Six Thinking Hats, Fishbone, empathy maps, Lean/Business Model Canvas, retrospectives, priority/RACI/Eisenhower matrices). NOT for diagrams — system/cloud architecture diagrams are render_cloudarchitecture, flowcharts/UML render_flowchart; NOT for mood/inspiration boards with imagery and color palettes (use render_moodframe); NOT for kanban-style status columns (use render_kanban) or UI/screen mockups and wireframes (use render_wireframe). Also available as the MCP tool `render_whiteboard`. The same payload works through either surface. - … - WhiteboardFrameData: Create a whiteboard WRAPPED IN a MockFlow IdeaBoard whiteboard frame (a single framed board component), for brainstorming and strategy canvases: sticky notes, sections, and named frameworks (SWOT, retro, empathy map, business model canvas, matrices). Differs from render_whiteboard, which drops the same content as LOOSE components on the canvas rather than inside a frame. NOT for diagrams: system/cloud architecture diagrams are render_cloudarchitecture, flowcharts/UML render_flowchart. Also available as the MCP tool `render_whiteboardframe`. The same payload works through either surface. - … - WireframeData: Create a UI WIREFRAME screen (render_wireframe) as a document of TYPED WIDGETS: navbar, appbar, sidebar, tabbar, button, input, card, list, table, chart, image box, hero, pricing and about sixty more, drawn by MockFlow in the frame's current style (outline, sketchy, blueprint, hi-fi, iOS liquid glass, Windows Fluent or Android Material, each in light or dark mode, with an optional brand colour and font, switched by the user at any time). You write the document, never HTML or CSS. Also available as the MCP tool `render_wireframe`. The same payload works through either surface. - … - object: Any other registry type. - object - `op` 'update', required - `id` string, required - `item` object, required - `position` Point - `x` number, required - `y` number, required - `size` Size - `width` number - `height` number - object - `op` 'delete', required - `id` string, required ## Response `202` Queued as one job for the whole batch. - Job - `id` string - `kind` 'item.create' | 'item.update' | 'item.delete' | 'item.batch' | 'item.record' | 'ai.generate' | 'ai.modify' | 'skill.apply' | 'board.export' - `status` 'queued' | 'running' | 'succeeded' | 'failed' - `progress` integer - `message` string: Human readable progress, for example "Placing kanban". - `result` object, nullable - `itemIds` string[] - `updated` string[] - `deleted` string[] - `creditsUsed` integer - `boardTitle` string, nullable - `skill` string, nullable - `convertedFrom` string - `sourceDeleted` boolean - `target` 'board' | 'frame' | 'item': board.export. What was drawn. - `format` 'png' | 'mp4': board.export. - `scale` 1 | 2: board.export. - `imageUrl` string, uri: board.export. The PNG. Anyone with this URL can open it. - `width` integer: board.export. The image's width in pixels. - `height` integer: board.export. The image's height in pixels. - `videoUrl` string, uri: board.export with format mp4. The MP4. Anyone with this URL can open it. - `fps` integer: board.export with format mp4. - `duration` number: board.export with format mp4. Seconds. - `bytes` integer: board.export with format mp4. The file's size. - `error` Error (unresolved $ref) - `createdAt` string, date-time - `finishedAt` string, date-time, nullable - `callbackUrl` string, nullable: Where the job's result is POSTed - `callback` object, nullable: The newest delivery to callbackUrl, once the job has finished. Null until then, and when there is no callbackUrl. - `url` string - `deliveryId` string - `status` 'pending' | 'retrying' | 'succeeded' | 'failed' | 'cancelled' - `attempts` integer - `responseStatus` integer, nullable - `error` string, nullable - `deliveredAt` string, date-time, nullable - `nextRetryAt` string, date-time, nullable ## Other responses - `422`: The body did not match the schema for this item type. - `429`: Too many requests. --- [API](https://skmtc.dev/mockflow/apis/mockflow-boards-api.md) - [All operations](https://skmtc.dev/mockflow/apis/mockflow-boards-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mockflow/apis/mockflow-boards-api/revisions/1a890390518c?raw)