designDeckInWhiteboard

{
  "type": "object",
  "properties": {
    "documentId": {
      "type": "string",
      "description": "The whiteboard the deck lives in. REQUIRED: a deck cannot exist without a whiteboard, and this is that whiteboard's id. If you do not already have a whiteboard id, ASK THE USER which whiteboard to design the deck in — never create one automatically. Only call createWhiteboard first if the user explicitly wants a new board."
    },
    "message": {
      "type": "string",
      "description": "This turn's message in plain language: the design brief on the first turn, an edit instruction later, or the user's ANSWER to a clarifying question the agent asked. On a follow-up turn, pass this together with the sessionId (or deckId) from the earlier call. If the user mentioned how many slides they want, ALSO pass slideCount with that number — never leave the count only in prose, and never outline more slides in this message than slideCount."
    },
    "sessionId": {
      "type": "string",
      "description": "The design conversation to continue, as returned by an earlier designDeckInWhiteboard call. Pass it together with message to answer a question, make an edit, or send a follow-up. Omit on the very first call to start a new conversation."
    },
    "deckId": {
      "type": "string",
      "description": "Optional. An existing deck to continue designing (usually you pass sessionId instead; when both are given the session's deck wins)."
    },
    "kind": {
      "type": "string",
      "enum": [
        "deck",
        "illustration",
        "design",
        "express"
      ],
      "description": "Which engine. 'deck' (default) = the premium on-brand HTML deck (conversational, build + edit); 'illustration' and 'design' are conversational variants. 'express' = the native, deterministic branded-executive deck (faster, lower fidelity, one-shot, not conversational)."
    },
    "title": {
      "type": "string",
      "description": "Optional title. If omitted, a clear one is derived from the brief."
    },
    "brandKitId": {
      "type": "string",
      "description": "Optional brand kit id (from listBrandKits) to theme the deck. If omitted, the organisation's effective brand is used."
    },
    "slideCount": {
      "type": "number",
      "description": "The number of slides to build — a hard requirement: the deck is built with exactly this many slides. SET THIS whenever the user states or implies a count, EXACT OR APPROXIMATE: '12 slides' → 12, 'about 15' / '15 or so' → 15, 'no more than 10' → 10. Never expand the user's number: if they said 'about 15', pass 15 and shape the brief to fit 15 — outlining 19 sections in the message does not raise the count, it just fights this parameter. It is PERSISTED on the conversation, so send it ONCE (on the turn that states it) and every later build turn of the same conversation carries it automatically; send it again only to CHANGE the target. It is honoured on edit turns too ('cut it to 8 slides'). THERE IS NO MAXIMUM: ask for 40, 60 or 100 slides and that is what gets built. Longer decks cost proportionally more (50 credits per 30 slides) and take proportionally longer. Omit ONLY when the user gave no count at all; the designer then chooses (typical 6 to 12)."
    },
    "imageCount": {
      "type": "number",
      "description": "Deprecated and ignored. Still accepted so existing callers do not break; passing it changes nothing."
    },
    "advancedDeckBuilding": {
      "type": "boolean",
      "description": "Optional, OFF by default. Build the deck with ADVANCED DECK BUILDING: instead of one composer pass, the deck is redrafted and reviewed over several rounds by a panel of design, brand, accessibility and copy reviewers, each round scoring the deck and listing what must be fixed. It usually produces a higher-quality deck, but it is not a guarantee. TIME: a standard build takes roughly 2 to 8 minutes; advanced deck building takes roughly 15 to 20 minutes. COST: 15 extra credits per depth level on top of the turn fee, so the default depth of 3 adds 45 credits and makes a 50-credit build cost 95. This is the user's deliberate choice, so only switch it on when they have asked for the best possible deck and accepted the wait and the cost. Quote the turn FIRST (call without confirm) so the user sees the real total before approving. Set it once and it is remembered for the rest of the conversation; pass false to turn it off again."
    },
    "advancedDeckBuildingDepth": {
      "type": "number",
      "description": "Optional. How many redraft-and-review rounds advanced deck building may run: 1 to 3, default 3. Each round is a full redraft plus four reviews, adds roughly 5 minutes, and costs 15 credits (depth 1 = +15, depth 2 = +30, depth 3 = +45). Ignored unless advancedDeckBuilding is true."
    },
    "attachments": {
      "type": "array",
      "description": "Optional reference images for THIS turn (up to 8; images only). The agent lifts palette, layout, and tone from them (it does not pixel-copy). Non-image attachments are ignored.",
      "items": {
        "type": "object",
        "description": "One reference image: give a public url, OR base64 data plus its mediaType.",
        "properties": {
          "url": {
            "type": "string",
            "description": "A public https URL to the image."
          },
          "data": {
            "type": "string",
            "description": "The image as base64 (no data: prefix). Provide mediaType alongside it."
          },
          "mediaType": {
            "type": "string",
            "description": "The image MIME type, e.g. 'image/png' or 'image/jpeg'."
          },
          "name": {
            "type": "string",
            "description": "Optional human-readable name for the image."
          },
          "type": {
            "type": "string",
            "description": "Optional attachment type hint, passed through to the design worker."
          }
        }
      }
    },
    "confirm": {
      "type": "boolean",
      "description": "Set true ONLY after the user has approved the cost (50 for a build, 10 for an edit). Leave unset/false on the first call of a turn to receive the cost quote plus balance. A clarifying question turn is never charged."
    }
  },
  "required": [
    "documentId",
    "message"
  ]
}