@stablebaseline/sdk 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/openapi.json CHANGED
@@ -2586,7 +2586,7 @@
2586
2586
  "/tools/getDocument": {
2587
2587
  "post": {
2588
2588
  "summary": "getDocument",
2589
- "description": "Read a document's content with line numbers. Returns numbered lines for use with editDocument. Diagrams/images appear as OMITTED markers with metadata (type, diagramId, nlDescription) — use getDiagramInDocument(diagramId) for full DSL code, or dedicated diagram/image tools to manage them. Pass includeDiagramDsl:true to inline each diagram's DSL and versionTimestamp directly into its DIAGRAM_OMITTED marker (saves a getDiagramInDocument call when you intend to read or edit diagrams).",
2589
+ "description": "Read a document's content with line numbers. content.text lines are formatted `NNNNN<TAB>content` (cat -n style); the number+tab prefix is DISPLAY ONLY — never part of the document — so when building editDocument anchor patches, copy only the text AFTER the tab. Reads paginate by lines (offset/limit, default 200): use content.totalLines and content.nextOffset to page. document.versionTimestamp is the optimistic-lock token that every mutating document tool accepts (as versionTimestamp; the older documentVersionTimestamp name also works) — and every mutating tool returns a fresh token, so you rarely need to re-read just to keep editing. Diagrams/images appear as OMITTED markers with metadata (type, diagramId, renderStatus, nlDescription) — use getDiagramInDocument(diagramId) for full DSL code, or pass includeDiagramDsl:true to inline each diagram's DSL and versionTimestamp directly into its DIAGRAM_OMITTED marker (saves a getDiagramInDocument call when you intend to read or edit diagrams).",
2590
2590
  "operationId": "getDocument",
2591
2591
  "tags": [
2592
2592
  "documents"
@@ -2714,7 +2714,7 @@
2714
2714
  "/tools/createDocument": {
2715
2715
  "post": {
2716
2716
  "summary": "createDocument",
2717
- "description": "Create a document from CDMD markdown. Call getCdmdLanguageGuide first if unfamiliar with syntax. Do not include DIAGRAM/IMAGE markers — insert them after with dedicated tools. Supports @-mentioning people: embed `<!-- REFERENCE: {\"type\":\"user\",\"id\":\"<user_uuid>\",\"label\":\"Name\"} -->` to notify a teammate. Use listAssignablePrincipals to look up the user_id from a name; mentions of users outside the project are silently dropped.",
2717
+ "description": "Create a document from CDMD markdown (standard Markdown plus SB extensions — call getCdmdLanguageGuide if unfamiliar). The body goes in `cdmd` (`content` is accepted as an alias). Do not include DIAGRAM/IMAGE markers — insert them after with dedicated tools. Returns the new document's id and versionTimestamp (the optimistic-lock token for subsequent edits). Supports @-mentioning people: embed `<!-- REFERENCE: {\"type\":\"user\",\"id\":\"<user_uuid>\",\"label\":\"Name\"} -->` to notify a teammate. Use listAssignablePrincipals to look up the user_id from a name; mentions of users outside the project are silently dropped.",
2718
2718
  "operationId": "createDocument",
2719
2719
  "tags": [
2720
2720
  "documents"
@@ -2736,7 +2736,12 @@
2736
2736
  "type": "string"
2737
2737
  },
2738
2738
  "cdmd": {
2739
- "type": "string"
2739
+ "type": "string",
2740
+ "description": "Document body in CDMD markdown. Alias: content."
2741
+ },
2742
+ "content": {
2743
+ "type": "string",
2744
+ "description": "Alias for cdmd — provide one of the two."
2740
2745
  },
2741
2746
  "position": {
2742
2747
  "type": "number",
@@ -2748,8 +2753,7 @@
2748
2753
  }
2749
2754
  },
2750
2755
  "required": [
2751
- "projectId",
2752
- "cdmd"
2756
+ "projectId"
2753
2757
  ]
2754
2758
  }
2755
2759
  }
@@ -2833,7 +2837,7 @@
2833
2837
  "/tools/editDocument": {
2834
2838
  "post": {
2835
2839
  "summary": "editDocument",
2836
- "description": "Edit a document: the PREFERRED tool for small targeted changes. Two patch dialects — do NOT mix them in one call. (1) ANCHOR patches {oldText, newText, before?, after?} — RECOMMENDED: replace an exact snippet of existing text with new text. oldText must match the document byte-for-byte AND be unique; if it occurs more than once, either expand oldText until it is unique, or add `before`/`after` (the EXACT text immediately before/after the match) to disambiguate. A no-match returns nearby context; an ambiguous match returns the occurrence count. Anchors do NOT drift, so you don't need fresh line numbers and they survive concurrent edits. Use newText:\"\" to delete. (2) LINE patches {startLine, endLine, replacement} — 1-based and INCLUSIVE: call getDocument first for line numbers; replace line 5 with {startLine:5,endLine:5}; INSERT before line N (deleting nothing) with {startLine:N,endLine:N-1}; append to an L-line document with {startLine:L+1,endLine:L}. Line numbers are ABSOLUTE and GO STALE after ANY edit — re-call getDocument before further line patches; out-of-range patches are rejected with the current line count. versionTimestamp from getDocument is required for optimistic locking, EXCEPT when dryRun:true. Set dryRun:true to apply the patches and get the resulting text back WITHOUT saving (verify before committing — kills retry loops). Do not edit or delete DIAGRAM/IMAGE marker lines (rejected with guidance) — use dedicated diagram/image tools. To @-mention a person, insert `<!-- REFERENCE: {\"type\":\"user\",\"id\":\"<user_uuid>\",\"label\":\"Name\"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.",
2840
+ "description": "Edit a document: the PREFERRED tool for small targeted changes. Two patch dialects — do NOT mix them in one call. (1) ANCHOR patches {oldText, newText, before?, after?} — RECOMMENDED: replace an exact snippet of existing text with new text. oldText must match the document byte-for-byte AND be unique; if it occurs more than once, either expand oldText until it is unique, or add `before`/`after` (the EXACT text immediately before/after the match) to disambiguate. A no-match returns nearby context; an ambiguous match returns the occurrence count. Anchors do NOT drift, so you don't need fresh line numbers and they survive concurrent edits. Use newText:\"\" to delete. (2) LINE patches {startLine, endLine, replacement} — 1-based and INCLUSIVE: call getDocument first for line numbers; replace line 5 with {startLine:5,endLine:5}; INSERT before line N (deleting nothing) with {startLine:N,endLine:N-1}; append to an L-line document with {startLine:L+1,endLine:L}. Line numbers are ABSOLUTE and GO STALE after ANY edit — re-call getDocument before further line patches; out-of-range patches are rejected with the current line count. versionTimestamp from getDocument (or from any mutating tool's response — they all return the fresh token) is required for optimistic locking, EXCEPT when dryRun:true. If your token is stale, the error tells you who changed the document, when, and the currentVersionTimestamp — anchor patches survive concurrent edits, so retrying with that token is usually safe. Set dryRun:true to apply the patches and get the resulting text back WITHOUT saving (verify before committing — kills retry loops). IMPORTANT: getDocument displays lines as `NNNNN<TAB>content`; that prefix is display-only — oldText/before/after must contain only the content AFTER the tab. Do not edit or delete DIAGRAM/IMAGE marker lines (rejected with guidance) — use dedicated diagram/image tools. To @-mention a person, insert `<!-- REFERENCE: {\"type\":\"user\",\"id\":\"<user_uuid>\",\"label\":\"Name\"} -->`; look up the user_id via listAssignablePrincipals. Mentioned users are notified automatically.",
2837
2841
  "operationId": "editDocument",
2838
2842
  "tags": [
2839
2843
  "documents"
@@ -2862,7 +2866,7 @@
2862
2866
  },
2863
2867
  "versionTimestamp": {
2864
2868
  "type": "number",
2865
- "description": "Version timestamp from getDocument() for optimistic locking. Required unless dryRun:true."
2869
+ "description": "Optimistic-lock token from getDocument() or any mutating tool's response. Required unless dryRun:true. (Alias accepted: documentVersionTimestamp.)"
2866
2870
  },
2867
2871
  "dryRun": {
2868
2872
  "type": "boolean",
@@ -3015,7 +3019,7 @@
3015
3019
  "/tools/findAndReplaceTextInDocument": {
3016
3020
  "post": {
3017
3021
  "summary": "findAndReplaceTextInDocument",
3018
- "description": "Find and replace EXACT substrings in a document (NOT regex: wildcards and patterns are matched literally). Replaces EVERY occurrence and returns the replacement count; best for renames and repeated phrases. For a single targeted change at a known location, prefer editDocument (line patches with optimistic locking). Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Note: when the `replace` value contains a `<!-- REFERENCE: {...} -->` marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.",
3022
+ "description": "Find and replace EXACT substrings in a document (NOT regex: wildcards and patterns are matched literally). Replaces EVERY occurrence and returns the replacement count; best for renames and repeated phrases. For a single targeted change at a known location, prefer editDocument (anchor patches). Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Returns document.versionTimestamp (the fresh optimistic-lock token) like every other mutating tool, so you can chain straight into editDocument or the diagram tools. Pass versionTimestamp to opt into optimistic locking (optional here — whole-document find/replace is position-independent). Note: when the `replace` value contains a `<!-- REFERENCE: {...} -->` marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.",
3019
3023
  "operationId": "findAndReplaceTextInDocument",
3020
3024
  "tags": [
3021
3025
  "documents"
@@ -3042,6 +3046,10 @@
3042
3046
  "type": "boolean",
3043
3047
  "description": "Case-sensitive matching. Default: true."
3044
3048
  },
3049
+ "versionTimestamp": {
3050
+ "type": "number",
3051
+ "description": "Optional optimistic-lock token from getDocument() or a previous write; validated when provided. (Alias accepted: documentVersionTimestamp.)"
3052
+ },
3045
3053
  "changeSummary": {
3046
3054
  "type": "string",
3047
3055
  "description": "Version history summary."
@@ -3134,7 +3142,7 @@
3134
3142
  "/tools/getDiagramInDocument": {
3135
3143
  "post": {
3136
3144
  "summary": "getDiagramInDocument",
3137
- "description": "Get a diagram's full details including raw DSL source code. Use diagramId from DIAGRAM_OMITTED markers in getDocument output. Returns diagramCode, type, name, nlDescription, and versionTimestamp.",
3145
+ "description": "Get a diagram's full details including raw DSL source code. Use diagramId from DIAGRAM_OMITTED markers in getDocument output. Returns diagramCode, type, name, nlDescription, renderStatus/renderError, and versionTimestamp — the diagram's optimistic-lock token for updateDiagramInDocument (every diagram write also returns it fresh).",
3138
3146
  "operationId": "getDiagramInDocument",
3139
3147
  "tags": [
3140
3148
  "diagrams"
@@ -3243,7 +3251,7 @@
3243
3251
  "/tools/insertDiagramInDocument": {
3244
3252
  "post": {
3245
3253
  "summary": "insertDiagramInDocument",
3246
- "description": "Insert a new diagram into a document. Call listDiagramTypes to find your type, then getDiagramTypeGuide for DSL syntax before writing diagramCode. Always set prompt + nlDescription to describe what the diagram shows (they are its saved description) and keep them accurate. After inserting, VERIFY the render — set returnImage:true (or call getDiagramImage) to actually SEE it — and if it is wrong or ugly, correct it with updateDiagramInDocument (provide the full updated diagramCode).",
3254
+ "description": "Insert a new diagram into a document. Call listDiagramTypes to find your type, then getDiagramTypeGuide for DSL syntax before writing diagramCode. The diagramCode is COMPILE-CHECKED BY RENDERING at write time: broken DSL is rejected with the renderer's error (fix and retry), and valid DSL is rendered + thumbnailed immediately so the document displays instantly everywhere. The response tells you what happened: diagram.renderStatus ('rendered' | 'pending_render' with renderError when the renderer was unavailable), plus fresh optimistic-lock tokens — document.versionTimestamp and diagram.versionTimestamp — so you can keep editing without re-reading. Always set prompt (and ideally nlDescription) to describe what the diagram shows. To SEE the result inline set returnImage:true, or call getDiagramImage afterwards; if it is wrong or ugly, correct it with updateDiagramInDocument (provide the full updated diagramCode).",
3247
3255
  "operationId": "insertDiagramInDocument",
3248
3256
  "tags": [
3249
3257
  "diagrams"
@@ -3260,7 +3268,7 @@
3260
3268
  },
3261
3269
  "documentVersionTimestamp": {
3262
3270
  "type": "number",
3263
- "description": "Version timestamp from getDocument() for optimistic locking."
3271
+ "description": "Optimistic-lock token: the document's versionTimestamp from getDocument() or any mutating tool's response. (Alias accepted: versionTimestamp.)"
3264
3272
  },
3265
3273
  "type": {
3266
3274
  "type": "string",
@@ -3340,14 +3348,9 @@
3340
3348
  },
3341
3349
  "required": [
3342
3350
  "documentId",
3343
- "documentVersionTimestamp",
3344
3351
  "type",
3345
3352
  "diagramCode",
3346
- "prompt",
3347
- "nlDescription",
3348
- "align",
3349
- "caption",
3350
- "afterLine"
3353
+ "prompt"
3351
3354
  ]
3352
3355
  }
3353
3356
  }
@@ -3431,7 +3434,7 @@
3431
3434
  "/tools/updateDiagramInDocument": {
3432
3435
  "post": {
3433
3436
  "summary": "updateDiagramInDocument",
3434
- "description": "Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. Provide a version lock: EITHER documentVersionTimestamp (from getDocument — locks the whole document) OR diagramVersionTimestamp (from getDiagramInDocument, or getDocument with includeDiagramDsl:true — locks just THIS diagram, so two agents can edit two different diagrams in the same document concurrently without a conflict). At least one is required; diagramVersionTimestamp is preferred for concurrency. IMPORTANT: To change what the diagram visually shows, you MUST provide diagramCode with the full updated DSL source. The prompt and nlDescription fields are metadata only and do NOT change the rendered diagram. After updating, re-render with getDiagramImage to confirm it now looks right (iterate if not), and keep prompt/nlDescription in step with what the diagram now shows.",
3437
+ "description": "Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax. New diagramCode is COMPILE-CHECKED BY RENDERING at write time — broken DSL is rejected with the renderer's error — and a valid change is re-rendered + re-thumbnailed immediately (response diagram.renderStatus tells you the outcome). Provide a version lock: diagramVersionTimestamp (from getDiagramInDocument, getDocument with includeDiagramDsl:true, or any diagram write's response — PREFERRED: locks just this diagram, so concurrent edits elsewhere in the document don't conflict; bare versionTimestamp is accepted as an alias) OR documentVersionTimestamp (locks the whole document). The response returns BOTH fresh tokens for chaining. Documents carrying a legacy marker (no embedded diagramId) are upgraded automatically on update. IMPORTANT: to change what the diagram visually shows you MUST provide diagramCode with the full updated DSL source — prompt/nlDescription are metadata only. After updating, view it with getDiagramImage and keep prompt/nlDescription in step with what the diagram now shows.",
3435
3438
  "operationId": "updateDiagramInDocument",
3436
3439
  "tags": [
3437
3440
  "diagrams"
@@ -3449,7 +3452,7 @@
3449
3452
  },
3450
3453
  "diagramCode": {
3451
3454
  "type": "string",
3452
- "description": "New diagram DSL source code. REQUIRED to change what the diagram visually renders. Call getDiagramTypeGuide for syntax. Must provide the COMPLETE updated DSL, not just the changed parts."
3455
+ "description": "New diagram DSL source code. REQUIRED to change what the diagram visually renders. Call getDiagramTypeGuide for syntax. Must provide the COMPLETE updated DSL, not just the changed parts. EXCEPTION — for type 'infographic', pass either a plain-English DESCRIPTION of the new infographic (the system designs, renders, and stores the AntV spec, same as insert) or complete AntV Infographic DSL (first line `infographic <template-name>`)."
3453
3456
  },
3454
3457
  "prompt": {
3455
3458
  "type": "string",
@@ -3494,7 +3497,7 @@
3494
3497
  },
3495
3498
  "diagramVersionTimestamp": {
3496
3499
  "type": "number",
3497
- "description": "Diagram-level optimistic lock: versionTimestamp of THIS diagram (from getDiagramInDocument, or getDocument with includeDiagramDsl:true). Pass this instead of documentVersionTimestamp to lock only this diagram, so concurrent edits to OTHER diagrams in the same document don't conflict. Preferred for multi-agent concurrency. The response returns the new diagram.diagramVersionTimestamp for chaining further edits."
3500
+ "description": "Diagram-level optimistic lock: versionTimestamp of THIS diagram (from getDiagramInDocument, getDocument with includeDiagramDsl:true, or a previous write's response). Preferred: locks only this diagram, so concurrent edits to OTHER diagrams in the same document don't conflict. (Alias accepted: versionTimestamp.) The response returns the new diagram.versionTimestamp for chaining further edits."
3498
3501
  }
3499
3502
  },
3500
3503
  "required": [
@@ -3582,7 +3585,7 @@
3582
3585
  "/tools/deleteDiagramInDocument": {
3583
3586
  "post": {
3584
3587
  "summary": "deleteDiagramInDocument",
3585
- "description": "Delete a diagram from a document.",
3588
+ "description": "Delete a diagram: removes the database record AND every reference to it in the document body — the current marker format plus legacy forms (markers without an embedded diagramId, and old plain-text `[Diagram: name]` placeholders). The response's removedFromBody says whether a marker was actually found in the body, and versionTimestamp is the document's fresh lock token.",
3586
3589
  "operationId": "deleteDiagramInDocument",
3587
3590
  "tags": [
3588
3591
  "diagrams"
@@ -3597,6 +3600,10 @@
3597
3600
  "diagramId": {
3598
3601
  "type": "string",
3599
3602
  "description": "Diagram ID from DIAGRAM_OMITTED markers."
3603
+ },
3604
+ "versionTimestamp": {
3605
+ "type": "number",
3606
+ "description": "Optional document optimistic-lock token; validated when provided. (Alias accepted: documentVersionTimestamp.)"
3600
3607
  }
3601
3608
  },
3602
3609
  "required": [
@@ -3926,6 +3933,20 @@
3926
3933
  "brandKitId": {
3927
3934
  "type": "string",
3928
3935
  "description": "Optional brand kit id (from listBrandKits) to theme a branded-executive deck. If omitted, the org's built-in default is used. Create one from just a logo (or a .pptx/.docx) via createBrandKit."
3936
+ },
3937
+ "sourceTranscript": {
3938
+ "type": "object",
3939
+ "description": "Design the board from a meeting transcript (exactly one of documentId or text). When set, the board is built as a 'meeting map' (topics, decisions, actions) from the transcript instead of from the goal alone. This mode is billed by transcript LENGTH — 2 credits per minute of transcript (10-minute minimum), not the flat 50; the first (unconfirmed) call returns the exact cost to relay to the user.",
3940
+ "properties": {
3941
+ "documentId": {
3942
+ "type": "string",
3943
+ "description": "The id of a Stable Baseline document holding the meeting transcript/notes to design from."
3944
+ },
3945
+ "text": {
3946
+ "type": "string",
3947
+ "description": "The raw transcript text to design from (pasted). Provide this OR documentId, not both."
3948
+ }
3949
+ }
3929
3950
  }
3930
3951
  },
3931
3952
  "required": [
@@ -4836,6 +4857,347 @@
4836
4857
  }
4837
4858
  }
4838
4859
  },
4860
+ "/tools/startMeetingScribe": {
4861
+ "post": {
4862
+ "summary": "startMeetingScribe",
4863
+ "description": "Invite the Stable Baseline Meeting Scribe bot to a LIVE meeting (Zoom, Google Meet, Microsoft Teams, or Webex) so it paints a live, editable whiteboard of the conversation as it happens: sticky notes and topic clusters, an agenda that ticks itself off, and decisions and actions pinned to rails, on a real board the team keeps working in afterwards. The bot transcribes only and stores no recording. WHITEBOARD IS REQUIRED: the scribe always paints an existing whiteboard, so documentId (the whiteboard's id) is required. If you do not have a whiteboard id, ASK THE USER which whiteboard to use; do not create one automatically. COST + APPROVAL: it bills 2 credits per minute in 5-minute blocks while it runs (a 60-minute meeting is about 120 credits; hard cap 180 minutes), and it needs the user's explicit approval. Call FIRST without confirm to get the exact quote plus the workspace balance, show that to the user, and only call again with confirm:true once they agree. Available on the Pro and Enterprise plans. It returns immediately with a sessionId; poll getMeetingScribeStatus to watch it join and paint, and stopMeetingScribe to end it. The user can also just remove the bot from the meeting to stop it.",
4864
+ "operationId": "startMeetingScribe",
4865
+ "tags": [
4866
+ "whiteboards"
4867
+ ],
4868
+ "requestBody": {
4869
+ "required": false,
4870
+ "content": {
4871
+ "application/json": {
4872
+ "schema": {
4873
+ "type": "object",
4874
+ "properties": {
4875
+ "documentId": {
4876
+ "type": "string",
4877
+ "description": "The whiteboard the scribe paints into. REQUIRED: a meeting scribe always paints an existing board. If you do not have a whiteboard id, ask the user which whiteboard to use; never create one automatically."
4878
+ },
4879
+ "meetingUrl": {
4880
+ "type": "string",
4881
+ "description": "The meeting link to join: a Zoom, Google Meet, Microsoft Teams, or Webex URL (https only). Any other host is rejected."
4882
+ },
4883
+ "agenda": {
4884
+ "type": "array",
4885
+ "description": "Optional agenda pre-drawn on the board as a left rail; each item gets a status sticker (pending, active, done) as the conversation reaches it. Omit to let the rail build itself from the topics that emerge.",
4886
+ "items": {
4887
+ "type": "object",
4888
+ "description": "One agenda item.",
4889
+ "properties": {
4890
+ "label": {
4891
+ "type": "string",
4892
+ "description": "The agenda item text."
4893
+ },
4894
+ "id": {
4895
+ "type": "string",
4896
+ "description": "Optional stable id; one is minted if omitted."
4897
+ }
4898
+ },
4899
+ "required": [
4900
+ "label"
4901
+ ]
4902
+ }
4903
+ },
4904
+ "settings": {
4905
+ "type": "object",
4906
+ "description": "Optional per-meeting settings: { language (BCP-47, e.g. 'en'), sttProvider ('assemblyai' default, or 'captions'), presentMode ('off' default, or 'camera'/'screenshare' to stream the live board back into the meeting), botName (override the default '{Org} Scribe (Stable Baseline)') }.",
4907
+ "additionalProperties": true
4908
+ },
4909
+ "confirm": {
4910
+ "type": "boolean",
4911
+ "description": "Set true ONLY after the user has approved the per-minute cost. Leave unset/false on the first call to receive the quote plus balance."
4912
+ }
4913
+ },
4914
+ "required": [
4915
+ "documentId",
4916
+ "meetingUrl"
4917
+ ]
4918
+ }
4919
+ }
4920
+ }
4921
+ },
4922
+ "responses": {
4923
+ "200": {
4924
+ "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
4925
+ "content": {
4926
+ "application/json": {
4927
+ "schema": {
4928
+ "type": "object",
4929
+ "additionalProperties": true
4930
+ }
4931
+ }
4932
+ }
4933
+ },
4934
+ "400": {
4935
+ "description": "Validation error.",
4936
+ "content": {
4937
+ "application/json": {
4938
+ "schema": {
4939
+ "$ref": "#/components/schemas/ErrorResponse"
4940
+ }
4941
+ }
4942
+ }
4943
+ },
4944
+ "401": {
4945
+ "description": "Missing or invalid credentials.",
4946
+ "content": {
4947
+ "application/json": {
4948
+ "schema": {
4949
+ "$ref": "#/components/schemas/ErrorResponse"
4950
+ }
4951
+ }
4952
+ }
4953
+ },
4954
+ "403": {
4955
+ "description": "Authenticated but lacking the required permission or feature flag.",
4956
+ "content": {
4957
+ "application/json": {
4958
+ "schema": {
4959
+ "$ref": "#/components/schemas/ErrorResponse"
4960
+ }
4961
+ }
4962
+ }
4963
+ },
4964
+ "404": {
4965
+ "description": "Resource not found.",
4966
+ "content": {
4967
+ "application/json": {
4968
+ "schema": {
4969
+ "$ref": "#/components/schemas/ErrorResponse"
4970
+ }
4971
+ }
4972
+ }
4973
+ },
4974
+ "422": {
4975
+ "description": "Body did not match the tool's input schema.",
4976
+ "content": {
4977
+ "application/json": {
4978
+ "schema": {
4979
+ "$ref": "#/components/schemas/ErrorResponse"
4980
+ }
4981
+ }
4982
+ }
4983
+ },
4984
+ "500": {
4985
+ "description": "Server error.",
4986
+ "content": {
4987
+ "application/json": {
4988
+ "schema": {
4989
+ "$ref": "#/components/schemas/ErrorResponse"
4990
+ }
4991
+ }
4992
+ }
4993
+ }
4994
+ }
4995
+ }
4996
+ },
4997
+ "/tools/getMeetingScribeStatus": {
4998
+ "post": {
4999
+ "summary": "getMeetingScribeStatus",
5000
+ "description": "Get a meeting scribe's status after startMeetingScribe: the session state (joining, in the waiting room, live in the call, paused, ending, ended, or failed), the live activity feed of what the scribe has painted, and the board it is painting. Give it the sessionId returned by startMeetingScribe. Poll every 15 to 30 seconds while the meeting runs. When the meeting ends the board holds the finished 'meeting map' (topics, decisions, actions, and a summary).",
5001
+ "operationId": "getMeetingScribeStatus",
5002
+ "tags": [
5003
+ "whiteboards"
5004
+ ],
5005
+ "requestBody": {
5006
+ "required": false,
5007
+ "content": {
5008
+ "application/json": {
5009
+ "schema": {
5010
+ "type": "object",
5011
+ "properties": {
5012
+ "sessionId": {
5013
+ "type": "string",
5014
+ "description": "The meeting scribe session to poll, as returned by startMeetingScribe."
5015
+ }
5016
+ },
5017
+ "required": [
5018
+ "sessionId"
5019
+ ]
5020
+ }
5021
+ }
5022
+ }
5023
+ },
5024
+ "responses": {
5025
+ "200": {
5026
+ "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
5027
+ "content": {
5028
+ "application/json": {
5029
+ "schema": {
5030
+ "type": "object",
5031
+ "additionalProperties": true
5032
+ }
5033
+ }
5034
+ }
5035
+ },
5036
+ "400": {
5037
+ "description": "Validation error.",
5038
+ "content": {
5039
+ "application/json": {
5040
+ "schema": {
5041
+ "$ref": "#/components/schemas/ErrorResponse"
5042
+ }
5043
+ }
5044
+ }
5045
+ },
5046
+ "401": {
5047
+ "description": "Missing or invalid credentials.",
5048
+ "content": {
5049
+ "application/json": {
5050
+ "schema": {
5051
+ "$ref": "#/components/schemas/ErrorResponse"
5052
+ }
5053
+ }
5054
+ }
5055
+ },
5056
+ "403": {
5057
+ "description": "Authenticated but lacking the required permission or feature flag.",
5058
+ "content": {
5059
+ "application/json": {
5060
+ "schema": {
5061
+ "$ref": "#/components/schemas/ErrorResponse"
5062
+ }
5063
+ }
5064
+ }
5065
+ },
5066
+ "404": {
5067
+ "description": "Resource not found.",
5068
+ "content": {
5069
+ "application/json": {
5070
+ "schema": {
5071
+ "$ref": "#/components/schemas/ErrorResponse"
5072
+ }
5073
+ }
5074
+ }
5075
+ },
5076
+ "422": {
5077
+ "description": "Body did not match the tool's input schema.",
5078
+ "content": {
5079
+ "application/json": {
5080
+ "schema": {
5081
+ "$ref": "#/components/schemas/ErrorResponse"
5082
+ }
5083
+ }
5084
+ }
5085
+ },
5086
+ "500": {
5087
+ "description": "Server error.",
5088
+ "content": {
5089
+ "application/json": {
5090
+ "schema": {
5091
+ "$ref": "#/components/schemas/ErrorResponse"
5092
+ }
5093
+ }
5094
+ }
5095
+ }
5096
+ }
5097
+ }
5098
+ },
5099
+ "/tools/stopMeetingScribe": {
5100
+ "post": {
5101
+ "summary": "stopMeetingScribe",
5102
+ "description": "Stop a running meeting scribe: the bot leaves the meeting and the board is finalised (tidy pass plus a summary frame). Give it the sessionId returned by startMeetingScribe. Billing stops at the current block; the user can also stop the scribe simply by removing the bot from the meeting.",
5103
+ "operationId": "stopMeetingScribe",
5104
+ "tags": [
5105
+ "whiteboards"
5106
+ ],
5107
+ "requestBody": {
5108
+ "required": false,
5109
+ "content": {
5110
+ "application/json": {
5111
+ "schema": {
5112
+ "type": "object",
5113
+ "properties": {
5114
+ "sessionId": {
5115
+ "type": "string",
5116
+ "description": "The meeting scribe session to stop, as returned by startMeetingScribe."
5117
+ }
5118
+ },
5119
+ "required": [
5120
+ "sessionId"
5121
+ ]
5122
+ }
5123
+ }
5124
+ }
5125
+ },
5126
+ "responses": {
5127
+ "200": {
5128
+ "description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
5129
+ "content": {
5130
+ "application/json": {
5131
+ "schema": {
5132
+ "type": "object",
5133
+ "additionalProperties": true
5134
+ }
5135
+ }
5136
+ }
5137
+ },
5138
+ "400": {
5139
+ "description": "Validation error.",
5140
+ "content": {
5141
+ "application/json": {
5142
+ "schema": {
5143
+ "$ref": "#/components/schemas/ErrorResponse"
5144
+ }
5145
+ }
5146
+ }
5147
+ },
5148
+ "401": {
5149
+ "description": "Missing or invalid credentials.",
5150
+ "content": {
5151
+ "application/json": {
5152
+ "schema": {
5153
+ "$ref": "#/components/schemas/ErrorResponse"
5154
+ }
5155
+ }
5156
+ }
5157
+ },
5158
+ "403": {
5159
+ "description": "Authenticated but lacking the required permission or feature flag.",
5160
+ "content": {
5161
+ "application/json": {
5162
+ "schema": {
5163
+ "$ref": "#/components/schemas/ErrorResponse"
5164
+ }
5165
+ }
5166
+ }
5167
+ },
5168
+ "404": {
5169
+ "description": "Resource not found.",
5170
+ "content": {
5171
+ "application/json": {
5172
+ "schema": {
5173
+ "$ref": "#/components/schemas/ErrorResponse"
5174
+ }
5175
+ }
5176
+ }
5177
+ },
5178
+ "422": {
5179
+ "description": "Body did not match the tool's input schema.",
5180
+ "content": {
5181
+ "application/json": {
5182
+ "schema": {
5183
+ "$ref": "#/components/schemas/ErrorResponse"
5184
+ }
5185
+ }
5186
+ }
5187
+ },
5188
+ "500": {
5189
+ "description": "Server error.",
5190
+ "content": {
5191
+ "application/json": {
5192
+ "schema": {
5193
+ "$ref": "#/components/schemas/ErrorResponse"
5194
+ }
5195
+ }
5196
+ }
5197
+ }
5198
+ }
5199
+ }
5200
+ },
4839
5201
  "/tools/createWhiteboard": {
4840
5202
  "post": {
4841
5203
  "summary": "createWhiteboard",
@@ -5892,7 +6254,7 @@
5892
6254
  "/tools/insertWhiteboardDiagram": {
5893
6255
  "post": {
5894
6256
  "summary": "insertWhiteboardDiagram",
5895
- "description": "Insert a real DIAGRAM (BPMN, Diagrams-as-Code / any DSL: mermaid, d2, plantuml, graphviz, …) into a whiteboard as an editable SB diagram element. Provide documentId, diagramType (call listDiagramTypes / getDiagramTypeGuide), and source (the DSL). The diagram is rendered to an image stored like a pasted image, and its editable source is kept in a sidecar so it stays a live, re-openable diagram on the board (double-click on the canvas opens the BPMN / code / AI editor). Options: caption (label beneath it), width/height to size it, and x/y or align ('left'|'center'|'right') to place it (defaults to the right of existing content). After inserting, call getWhiteboardImage to see it and verify it rendered correctly (fix the source and re-insert if it is wrong). For a plain picture (not a diagram) use insertWhiteboardImage; to generate a diagram image WITHOUT inserting use renderDiagram.",
6257
+ "description": "Insert (or re-render in place) a real DIAGRAM (BPMN, Diagrams-as-Code / any DSL: mermaid, d2, plantuml, graphviz, …) on a whiteboard as an editable SB diagram element. Provide documentId, diagramType (call listDiagramTypes / getDiagramTypeGuide), and source (the DSL). The diagram is rendered to an image stored like a pasted image, and its editable source is kept in a sidecar so it stays a live, re-openable diagram (double-click on the canvas opens the BPMN / code / AI editor). Options: caption (label beneath it), width/height to size it (auto width caps at 480px; an explicit width may go up to 1200px), and x/y or align ('left'|'center'|'right') to place it (defaults to the right of existing content). Pass updateElementId to UPDATE an existing embedded diagram in place — re-render + replace its image and DSL while keeping the same element id and board position (used to live-edit a diagram as it evolves); if that id is not on the board yet it is created carrying that id. After inserting, call getWhiteboardImage to see it and verify it rendered correctly (fix the source and re-insert if it is wrong). For a plain picture (not a diagram) use insertWhiteboardImage; to generate a diagram image WITHOUT inserting use renderDiagram.",
5896
6258
  "operationId": "insertWhiteboardDiagram",
5897
6259
  "tags": [
5898
6260
  "whiteboards"
@@ -5922,7 +6284,7 @@
5922
6284
  },
5923
6285
  "width": {
5924
6286
  "type": "number",
5925
- "description": "Display width in px (aspect ratio preserved). Defaults to a capped natural size."
6287
+ "description": "Display width in px (aspect ratio preserved). Auto-size caps at 480px; an explicit width is honoured up to 1200px."
5926
6288
  },
5927
6289
  "height": {
5928
6290
  "type": "number",
@@ -5930,11 +6292,11 @@
5930
6292
  },
5931
6293
  "x": {
5932
6294
  "type": "number",
5933
- "description": "Top-left x on the canvas. Omit to auto-place."
6295
+ "description": "Top-left x on the canvas. Omit to auto-place (or to keep the existing position when updateElementId is given)."
5934
6296
  },
5935
6297
  "y": {
5936
6298
  "type": "number",
5937
- "description": "Top-left y on the canvas. Omit to auto-place."
6299
+ "description": "Top-left y on the canvas. Omit to auto-place (or to keep the existing position when updateElementId is given)."
5938
6300
  },
5939
6301
  "align": {
5940
6302
  "type": "string",
@@ -5944,6 +6306,17 @@
5944
6306
  "right"
5945
6307
  ],
5946
6308
  "description": "Horizontal alignment relative to existing content (placed below it). Ignored if x/y given."
6309
+ },
6310
+ "updateElementId": {
6311
+ "type": "string",
6312
+ "description": "Element id of an EXISTING embedded diagram to re-render and replace in place (keeps the element id + board position). Omit for a fresh insert. If the id is not on the board, a new element is created with it."
6313
+ },
6314
+ "fit": {
6315
+ "type": "string",
6316
+ "enum": [
6317
+ "contain"
6318
+ ],
6319
+ "description": "When 'contain' AND both width and height are given, treat width/height as a BOUNDING BOX: the diagram is scaled to its natural aspect ratio to fit inside the box (never upscaled past 1.5x natural) and centred, so it never stretches. The response's diagram.{x,y,width,height} carry the final drawn geometry. Omit for the exact width/height behaviour."
5947
6320
  }
5948
6321
  },
5949
6322
  "required": [
@@ -6809,7 +7182,7 @@
6809
7182
  "/tools/getDiagramImage": {
6810
7183
  "post": {
6811
7184
  "summary": "getDiagramImage",
6812
- "description": "Render a diagram that ALREADY exists in a document to an IMAGE (svg/png/jpeg @1x/2x/3x) and return it — a temporary signed URL (expires in 1 hour) plus, for png/jpeg, the image inline so you can see it. Pass the diagramId (from getDocument's DIAGRAM markers or getDiagramInDocument). Reuses the diagram's cached server render when available (pixel-identical to the editor). Use renderDiagram instead to generate from raw DSL without an existing diagram.",
7185
+ "description": "Render a diagram that ALREADY exists in a document to an IMAGE (svg/png/jpeg @1x/2x/3x) and return it — a temporary signed URL (expires in 1 hour) plus, for png/jpeg, the image inline so you can see it. Pass the diagramId (from getDocument's DIAGRAM markers or getDiagramInDocument). Reuses the diagram's cached server render when available (pixel-identical to the editor); when the diagram has no cached render yet, the fresh render is persisted back to the document (persistedRender:true in the response), so reading repairs unrendered diagrams. Use renderDiagram instead to generate from raw DSL without an existing diagram.",
6813
7186
  "operationId": "getDiagramImage",
6814
7187
  "tags": [
6815
7188
  "diagrams"
@@ -7531,7 +7904,7 @@
7531
7904
  },
7532
7905
  "documentVersionTimestamp": {
7533
7906
  "type": "number",
7534
- "description": "Version timestamp from getDocument() for optimistic locking."
7907
+ "description": "Optimistic-lock token: the document's versionTimestamp from getDocument() or any mutating tool's response. (Alias accepted: versionTimestamp.)"
7535
7908
  },
7536
7909
  "imageBase64": {
7537
7910
  "type": "string",
@@ -7588,7 +7961,6 @@
7588
7961
  },
7589
7962
  "required": [
7590
7963
  "documentId",
7591
- "documentVersionTimestamp",
7592
7964
  "nlDescription",
7593
7965
  "caption"
7594
7966
  ]
@@ -7674,7 +8046,7 @@
7674
8046
  "/tools/updateImageInDocument": {
7675
8047
  "post": {
7676
8048
  "summary": "updateImageInDocument",
7677
- "description": "Update image metadata (alt, caption, dimensions, alignment). Requires documentVersionTimestamp from getDocument for optimistic locking.",
8049
+ "description": "Update image metadata (alt, caption, dimensions, alignment). Requires the document's versionTimestamp (from getDocument or any mutating tool's response) for optimistic locking.",
7678
8050
  "operationId": "updateImageInDocument",
7679
8051
  "tags": [
7680
8052
  "images"
@@ -7692,7 +8064,7 @@
7692
8064
  },
7693
8065
  "documentVersionTimestamp": {
7694
8066
  "type": "number",
7695
- "description": "Version timestamp from getDocument() for optimistic locking."
8067
+ "description": "Optimistic-lock token: the document's versionTimestamp from getDocument() or any mutating tool's response. (Alias accepted: versionTimestamp.)"
7696
8068
  },
7697
8069
  "alt": {
7698
8070
  "type": "string",
@@ -7725,8 +8097,7 @@
7725
8097
  }
7726
8098
  },
7727
8099
  "required": [
7728
- "imageId",
7729
- "documentVersionTimestamp"
8100
+ "imageId"
7730
8101
  ]
7731
8102
  }
7732
8103
  }