@stablebaseline/sdk 0.5.0 → 0.5.2
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/dist/index.d.cts +634 -56
- package/dist/index.d.ts +634 -56
- package/openapi.json +947 -82
- package/package.json +2 -2
- package/src/types.generated.ts +634 -56
package/openapi.json
CHANGED
|
@@ -265,7 +265,7 @@
|
|
|
265
265
|
"/tools/listDiagramTypes": {
|
|
266
266
|
"post": {
|
|
267
267
|
"summary": "listDiagramTypes",
|
|
268
|
-
"description": "List supported diagram types. Use the returned `type` field
|
|
268
|
+
"description": "List supported diagram types. Pass `query` to search by name OR intent (keyword + semantic): e.g. 'circuit diagram', 'wiring harness', 'timing waveform', 'network topology', 'database schema'. Use the returned `type` field with getDiagramTypeGuide (DSL instructions + example) and insertDiagramInDocument / renderDiagram.",
|
|
269
269
|
"operationId": "listDiagramTypes",
|
|
270
270
|
"tags": [
|
|
271
271
|
"diagrams"
|
|
@@ -278,7 +278,8 @@
|
|
|
278
278
|
"type": "object",
|
|
279
279
|
"properties": {
|
|
280
280
|
"query": {
|
|
281
|
-
"type": "string"
|
|
281
|
+
"type": "string",
|
|
282
|
+
"description": "Keyword or intent, e.g. 'circuit', 'wiring harness', 'timing'. Semantic-backed: matches descriptions, not just names."
|
|
282
283
|
},
|
|
283
284
|
"enabledOnly": {
|
|
284
285
|
"type": "boolean"
|
|
@@ -917,10 +918,14 @@
|
|
|
917
918
|
"type": "string",
|
|
918
919
|
"description": "Workspace UUID. Optional but recommended — when present, the result includes ALL org members; when omitted, only direct project grants + team-expanded users are returned."
|
|
919
920
|
},
|
|
920
|
-
"
|
|
921
|
+
"query": {
|
|
921
922
|
"type": "string",
|
|
922
923
|
"description": "Optional ILIKE search filter — matched against display_name + email (users) and team name (teams)."
|
|
923
924
|
},
|
|
925
|
+
"q": {
|
|
926
|
+
"type": "string",
|
|
927
|
+
"description": "Deprecated alias for `query`, still accepted. Prefer `query` — that is the name every other list tool uses."
|
|
928
|
+
},
|
|
924
929
|
"kind": {
|
|
925
930
|
"type": "string",
|
|
926
931
|
"enum": [
|
|
@@ -1044,10 +1049,14 @@
|
|
|
1044
1049
|
"type": "string",
|
|
1045
1050
|
"description": "Workspace UUID. The parent organization is resolved from v_workspaces."
|
|
1046
1051
|
},
|
|
1047
|
-
"
|
|
1052
|
+
"query": {
|
|
1048
1053
|
"type": "string",
|
|
1049
1054
|
"description": "Optional ILIKE search on team name/slug."
|
|
1050
1055
|
},
|
|
1056
|
+
"q": {
|
|
1057
|
+
"type": "string",
|
|
1058
|
+
"description": "Deprecated alias for `query`, still accepted. Prefer `query` — that is the name every other list tool uses."
|
|
1059
|
+
},
|
|
1051
1060
|
"includeMembers": {
|
|
1052
1061
|
"type": "boolean",
|
|
1053
1062
|
"description": "When true, each team gets a `members` array (user_id, role, joined_at). Capped at 500 total members across the page. Default false."
|
|
@@ -1360,7 +1369,7 @@
|
|
|
1360
1369
|
"/tools/listWorkspaces": {
|
|
1361
1370
|
"post": {
|
|
1362
1371
|
"summary": "listWorkspaces",
|
|
1363
|
-
"description": "List workspaces you have access to. Supports query filtering by name/slug.",
|
|
1372
|
+
"description": "List workspaces you have access to. Scope to one organisation with organisationId (a structural filter — use it rather than `query`, which only searches names/slugs). Supports query filtering by name/slug.",
|
|
1364
1373
|
"operationId": "listWorkspaces",
|
|
1365
1374
|
"tags": [
|
|
1366
1375
|
"navigation"
|
|
@@ -1372,6 +1381,14 @@
|
|
|
1372
1381
|
"schema": {
|
|
1373
1382
|
"type": "object",
|
|
1374
1383
|
"properties": {
|
|
1384
|
+
"organisationId": {
|
|
1385
|
+
"type": "string",
|
|
1386
|
+
"description": "Return only workspaces in this organisation. Use listOrganisations to find the id. (organizationId is accepted as a spelling alias.)"
|
|
1387
|
+
},
|
|
1388
|
+
"organizationId": {
|
|
1389
|
+
"type": "string",
|
|
1390
|
+
"description": "Spelling alias for organisationId."
|
|
1391
|
+
},
|
|
1375
1392
|
"query": {
|
|
1376
1393
|
"type": "string"
|
|
1377
1394
|
},
|
|
@@ -2184,7 +2201,7 @@
|
|
|
2184
2201
|
"/tools/listDocuments": {
|
|
2185
2202
|
"post": {
|
|
2186
2203
|
"summary": "listDocuments",
|
|
2187
|
-
"description": "List AND grep documents in a project, workspace, or folder. `query` does a full-content search across each document's body (not just the title) and returns the matching lines — like grep across your docs. Each returned document includes `contentMatches: [{line, text, context?}]` and `matchCount`; the `text` is anchor-ready (paste it straight into editDocument's oldText). Use isRegex:true for regular-expression search (e.g. \"TODO\\(.*\\)\", \"ACME-\\d+\"), caseSensitive for exact case, and contextLines for surrounding lines (grep -C). versionTimestamp is returned per document so you can edit straight from the results without a getDocument round-trip. Also supports date filtering.",
|
|
2204
|
+
"description": "List AND grep documents in a project, workspace, or folder. `query` does a full-content search across each document's body (not just the title) and returns the matching lines — like grep across your docs. Each returned document includes `contentMatches: [{line, text, context?}]` and `matchCount`; the `text` is anchor-ready (paste it straight into editDocument's oldText). Use isRegex:true for regular-expression search (e.g. \"TODO\\(.*\\)\", \"ACME-\\d+\"), caseSensitive for exact case, and contextLines for surrounding lines (grep -C). versionTimestamp is returned per document so you can edit straight from the results without a getDocument round-trip. Also supports date filtering. SCOPE HONESTY — read this before concluding something is absent: only documents that actually matched are returned (a document is never listed with matchCount 0 just because it was in scope), and the `grep` block reports `scannedDocuments` against `totalDocumentsInScope`. When `truncated` is true the search covered only part of the scope, so an absence is NOT proof; repeat with `scanOffset` set to the returned `nextScanOffset` until that field is gone, and union the results. A document too large to read is returned with `contentSearchSkipped: true` and NO matchCount, because its body was never searched.",
|
|
2188
2205
|
"operationId": "listDocuments",
|
|
2189
2206
|
"tags": [
|
|
2190
2207
|
"documents"
|
|
@@ -2229,7 +2246,12 @@
|
|
|
2229
2246
|
"type": "number"
|
|
2230
2247
|
},
|
|
2231
2248
|
"offset": {
|
|
2232
|
-
"type": "number"
|
|
2249
|
+
"type": "number",
|
|
2250
|
+
"description": "Pagination offset over the MATCHES. When searching, use scanOffset (not this) to reach documents the scan has not covered."
|
|
2251
|
+
},
|
|
2252
|
+
"scanOffset": {
|
|
2253
|
+
"type": "number",
|
|
2254
|
+
"description": "Search-only. Where to start the document scan within the scope. One call examines a bounded window; when the response reports truncated:true it also returns nextScanOffset — repeat with scanOffset set to that value until nextScanOffset is absent, and union the results, to search a scope larger than one window exhaustively."
|
|
2233
2255
|
},
|
|
2234
2256
|
"fromDate": {
|
|
2235
2257
|
"type": "string",
|
|
@@ -2460,7 +2482,7 @@
|
|
|
2460
2482
|
"/tools/getFolderHierarchy": {
|
|
2461
2483
|
"post": {
|
|
2462
2484
|
"summary": "getFolderHierarchy",
|
|
2463
|
-
"description": "Get the folder and document tree
|
|
2485
|
+
"description": "Get the folder and document tree. Pass folderId for the subtree under one folder, or projectId for the project's ENTIRE folder tree from the root (no need to reassemble listFolders' flat list by parentId). Alias for getProjectHierarchy.",
|
|
2464
2486
|
"operationId": "getFolderHierarchy",
|
|
2465
2487
|
"tags": [
|
|
2466
2488
|
"navigation"
|
|
@@ -2472,9 +2494,13 @@
|
|
|
2472
2494
|
"schema": {
|
|
2473
2495
|
"type": "object",
|
|
2474
2496
|
"properties": {
|
|
2497
|
+
"projectId": {
|
|
2498
|
+
"type": "string",
|
|
2499
|
+
"description": "Return the whole project's folder tree from the root. Provide this or folderId."
|
|
2500
|
+
},
|
|
2475
2501
|
"folderId": {
|
|
2476
2502
|
"type": "string",
|
|
2477
|
-
"description": "The folder ID to start from."
|
|
2503
|
+
"description": "The folder ID to start from. Omit and pass projectId to get the project root hierarchy."
|
|
2478
2504
|
},
|
|
2479
2505
|
"maxDepth": {
|
|
2480
2506
|
"type": "number",
|
|
@@ -2500,10 +2526,7 @@
|
|
|
2500
2526
|
"type": "string",
|
|
2501
2527
|
"description": "Date field to filter. Default: updated_at."
|
|
2502
2528
|
}
|
|
2503
|
-
}
|
|
2504
|
-
"required": [
|
|
2505
|
-
"folderId"
|
|
2506
|
-
]
|
|
2529
|
+
}
|
|
2507
2530
|
}
|
|
2508
2531
|
}
|
|
2509
2532
|
}
|
|
@@ -2586,7 +2609,7 @@
|
|
|
2586
2609
|
"/tools/getDocument": {
|
|
2587
2610
|
"post": {
|
|
2588
2611
|
"summary": "getDocument",
|
|
2589
|
-
"description": "Read a document's content with line numbers.
|
|
2612
|
+
"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
2613
|
"operationId": "getDocument",
|
|
2591
2614
|
"tags": [
|
|
2592
2615
|
"documents"
|
|
@@ -2598,9 +2621,13 @@
|
|
|
2598
2621
|
"schema": {
|
|
2599
2622
|
"type": "object",
|
|
2600
2623
|
"properties": {
|
|
2624
|
+
"projectId": {
|
|
2625
|
+
"type": "string",
|
|
2626
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
2627
|
+
},
|
|
2601
2628
|
"documentId": {
|
|
2602
2629
|
"type": "string",
|
|
2603
|
-
"description": "The document ID to read."
|
|
2630
|
+
"description": "The document ID to read. Accepts either the UUID or the friendly id (e.g. DOC-815); friendly ids are resolved within your organisation."
|
|
2604
2631
|
},
|
|
2605
2632
|
"offset": {
|
|
2606
2633
|
"type": "number",
|
|
@@ -2714,7 +2741,7 @@
|
|
|
2714
2741
|
"/tools/createDocument": {
|
|
2715
2742
|
"post": {
|
|
2716
2743
|
"summary": "createDocument",
|
|
2717
|
-
"description": "Create a document from CDMD markdown
|
|
2744
|
+
"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). A leading `---` YAML frontmatter block is stored and preserved: title/exported_at/generator are managed by the platform, and any other key you set (doc_type, authority_state, owner, conforms_to, …) round-trips untouched through reads and later edits. 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
2745
|
"operationId": "createDocument",
|
|
2719
2746
|
"tags": [
|
|
2720
2747
|
"documents"
|
|
@@ -2736,7 +2763,12 @@
|
|
|
2736
2763
|
"type": "string"
|
|
2737
2764
|
},
|
|
2738
2765
|
"cdmd": {
|
|
2739
|
-
"type": "string"
|
|
2766
|
+
"type": "string",
|
|
2767
|
+
"description": "Document body in CDMD markdown. Alias: content."
|
|
2768
|
+
},
|
|
2769
|
+
"content": {
|
|
2770
|
+
"type": "string",
|
|
2771
|
+
"description": "Alias for cdmd — provide one of the two."
|
|
2740
2772
|
},
|
|
2741
2773
|
"position": {
|
|
2742
2774
|
"type": "number",
|
|
@@ -2748,8 +2780,7 @@
|
|
|
2748
2780
|
}
|
|
2749
2781
|
},
|
|
2750
2782
|
"required": [
|
|
2751
|
-
"projectId"
|
|
2752
|
-
"cdmd"
|
|
2783
|
+
"projectId"
|
|
2753
2784
|
]
|
|
2754
2785
|
}
|
|
2755
2786
|
}
|
|
@@ -2833,7 +2864,7 @@
|
|
|
2833
2864
|
"/tools/editDocument": {
|
|
2834
2865
|
"post": {
|
|
2835
2866
|
"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.",
|
|
2867
|
+
"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
2868
|
"operationId": "editDocument",
|
|
2838
2869
|
"tags": [
|
|
2839
2870
|
"documents"
|
|
@@ -2845,6 +2876,10 @@
|
|
|
2845
2876
|
"schema": {
|
|
2846
2877
|
"type": "object",
|
|
2847
2878
|
"properties": {
|
|
2879
|
+
"projectId": {
|
|
2880
|
+
"type": "string",
|
|
2881
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
2882
|
+
},
|
|
2848
2883
|
"documentId": {
|
|
2849
2884
|
"type": "string"
|
|
2850
2885
|
},
|
|
@@ -2853,16 +2888,23 @@
|
|
|
2853
2888
|
"description": "New title."
|
|
2854
2889
|
},
|
|
2855
2890
|
"folderId": {
|
|
2856
|
-
"type":
|
|
2857
|
-
|
|
2891
|
+
"type": [
|
|
2892
|
+
"string",
|
|
2893
|
+
"null"
|
|
2894
|
+
],
|
|
2895
|
+
"description": "MOVE the document into this folder (null moves it to the project root). Send it with patches:[] to file the document without touching its content — a folder-only move updates folder_id, creates NO version-history entry, and does not bump the document version. To move many documents at once use reorderDocuments, which takes folderId per item."
|
|
2858
2896
|
},
|
|
2859
2897
|
"position": {
|
|
2860
2898
|
"type": "number",
|
|
2861
|
-
"description": "Sort position within the parent folder. Use to reposition a single document. For batch sibling reorder, use reorderDocuments."
|
|
2899
|
+
"description": "Sort position within the parent folder. Use to reposition a single document; like folderId, a position-only change creates no version. For batch sibling reorder/move, use reorderDocuments."
|
|
2862
2900
|
},
|
|
2863
2901
|
"versionTimestamp": {
|
|
2864
2902
|
"type": "number",
|
|
2865
|
-
"description": "
|
|
2903
|
+
"description": "Optimistic-lock token from getDocument() or any mutating tool's response. Required unless dryRun:true. (Alias accepted: documentVersionTimestamp.)"
|
|
2904
|
+
},
|
|
2905
|
+
"expectedVersion": {
|
|
2906
|
+
"type": "number",
|
|
2907
|
+
"description": "Legacy integer version guard, checked in addition to versionTimestamp. Prefer versionTimestamp — this exists for older clients and is optional."
|
|
2866
2908
|
},
|
|
2867
2909
|
"dryRun": {
|
|
2868
2910
|
"type": "boolean",
|
|
@@ -3015,7 +3057,7 @@
|
|
|
3015
3057
|
"/tools/findAndReplaceTextInDocument": {
|
|
3016
3058
|
"post": {
|
|
3017
3059
|
"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 (
|
|
3060
|
+
"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
3061
|
"operationId": "findAndReplaceTextInDocument",
|
|
3020
3062
|
"tags": [
|
|
3021
3063
|
"documents"
|
|
@@ -3027,6 +3069,10 @@
|
|
|
3027
3069
|
"schema": {
|
|
3028
3070
|
"type": "object",
|
|
3029
3071
|
"properties": {
|
|
3072
|
+
"projectId": {
|
|
3073
|
+
"type": "string",
|
|
3074
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
3075
|
+
},
|
|
3030
3076
|
"documentId": {
|
|
3031
3077
|
"type": "string"
|
|
3032
3078
|
},
|
|
@@ -3042,6 +3088,10 @@
|
|
|
3042
3088
|
"type": "boolean",
|
|
3043
3089
|
"description": "Case-sensitive matching. Default: true."
|
|
3044
3090
|
},
|
|
3091
|
+
"versionTimestamp": {
|
|
3092
|
+
"type": "number",
|
|
3093
|
+
"description": "Optional optimistic-lock token from getDocument() or a previous write; validated when provided. (Alias accepted: documentVersionTimestamp.)"
|
|
3094
|
+
},
|
|
3045
3095
|
"changeSummary": {
|
|
3046
3096
|
"type": "string",
|
|
3047
3097
|
"description": "Version history summary."
|
|
@@ -3134,7 +3184,7 @@
|
|
|
3134
3184
|
"/tools/getDiagramInDocument": {
|
|
3135
3185
|
"post": {
|
|
3136
3186
|
"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.",
|
|
3187
|
+
"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
3188
|
"operationId": "getDiagramInDocument",
|
|
3139
3189
|
"tags": [
|
|
3140
3190
|
"diagrams"
|
|
@@ -3243,7 +3293,7 @@
|
|
|
3243
3293
|
"/tools/insertDiagramInDocument": {
|
|
3244
3294
|
"post": {
|
|
3245
3295
|
"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.
|
|
3296
|
+
"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
3297
|
"operationId": "insertDiagramInDocument",
|
|
3248
3298
|
"tags": [
|
|
3249
3299
|
"diagrams"
|
|
@@ -3255,12 +3305,16 @@
|
|
|
3255
3305
|
"schema": {
|
|
3256
3306
|
"type": "object",
|
|
3257
3307
|
"properties": {
|
|
3308
|
+
"projectId": {
|
|
3309
|
+
"type": "string",
|
|
3310
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
3311
|
+
},
|
|
3258
3312
|
"documentId": {
|
|
3259
3313
|
"type": "string"
|
|
3260
3314
|
},
|
|
3261
3315
|
"documentVersionTimestamp": {
|
|
3262
3316
|
"type": "number",
|
|
3263
|
-
"description": "
|
|
3317
|
+
"description": "Optimistic-lock token: the document's versionTimestamp from getDocument() or any mutating tool's response. (Alias accepted: versionTimestamp.)"
|
|
3264
3318
|
},
|
|
3265
3319
|
"type": {
|
|
3266
3320
|
"type": "string",
|
|
@@ -3340,14 +3394,9 @@
|
|
|
3340
3394
|
},
|
|
3341
3395
|
"required": [
|
|
3342
3396
|
"documentId",
|
|
3343
|
-
"documentVersionTimestamp",
|
|
3344
3397
|
"type",
|
|
3345
3398
|
"diagramCode",
|
|
3346
|
-
"prompt"
|
|
3347
|
-
"nlDescription",
|
|
3348
|
-
"align",
|
|
3349
|
-
"caption",
|
|
3350
|
-
"afterLine"
|
|
3399
|
+
"prompt"
|
|
3351
3400
|
]
|
|
3352
3401
|
}
|
|
3353
3402
|
}
|
|
@@ -3431,7 +3480,7 @@
|
|
|
3431
3480
|
"/tools/updateDiagramInDocument": {
|
|
3432
3481
|
"post": {
|
|
3433
3482
|
"summary": "updateDiagramInDocument",
|
|
3434
|
-
"description": "Update a diagram's code, description, or properties. Call getDiagramTypeGuide for DSL syntax.
|
|
3483
|
+
"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
3484
|
"operationId": "updateDiagramInDocument",
|
|
3436
3485
|
"tags": [
|
|
3437
3486
|
"diagrams"
|
|
@@ -3449,7 +3498,7 @@
|
|
|
3449
3498
|
},
|
|
3450
3499
|
"diagramCode": {
|
|
3451
3500
|
"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."
|
|
3501
|
+
"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
3502
|
},
|
|
3454
3503
|
"prompt": {
|
|
3455
3504
|
"type": "string",
|
|
@@ -3494,7 +3543,7 @@
|
|
|
3494
3543
|
},
|
|
3495
3544
|
"diagramVersionTimestamp": {
|
|
3496
3545
|
"type": "number",
|
|
3497
|
-
"description": "Diagram-level optimistic lock: versionTimestamp of THIS diagram (from getDiagramInDocument,
|
|
3546
|
+
"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
3547
|
}
|
|
3499
3548
|
},
|
|
3500
3549
|
"required": [
|
|
@@ -3582,7 +3631,7 @@
|
|
|
3582
3631
|
"/tools/deleteDiagramInDocument": {
|
|
3583
3632
|
"post": {
|
|
3584
3633
|
"summary": "deleteDiagramInDocument",
|
|
3585
|
-
"description": "Delete a diagram
|
|
3634
|
+
"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
3635
|
"operationId": "deleteDiagramInDocument",
|
|
3587
3636
|
"tags": [
|
|
3588
3637
|
"diagrams"
|
|
@@ -3597,6 +3646,10 @@
|
|
|
3597
3646
|
"diagramId": {
|
|
3598
3647
|
"type": "string",
|
|
3599
3648
|
"description": "Diagram ID from DIAGRAM_OMITTED markers."
|
|
3649
|
+
},
|
|
3650
|
+
"versionTimestamp": {
|
|
3651
|
+
"type": "number",
|
|
3652
|
+
"description": "Optional document optimistic-lock token; validated when provided. (Alias accepted: documentVersionTimestamp.)"
|
|
3600
3653
|
}
|
|
3601
3654
|
},
|
|
3602
3655
|
"required": [
|
|
@@ -3698,6 +3751,10 @@
|
|
|
3698
3751
|
"properties": {
|
|
3699
3752
|
"documentId": {
|
|
3700
3753
|
"type": "string"
|
|
3754
|
+
},
|
|
3755
|
+
"projectId": {
|
|
3756
|
+
"type": "string",
|
|
3757
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Ignored when documentId is a UUID."
|
|
3701
3758
|
}
|
|
3702
3759
|
},
|
|
3703
3760
|
"required": [
|
|
@@ -3926,6 +3983,20 @@
|
|
|
3926
3983
|
"brandKitId": {
|
|
3927
3984
|
"type": "string",
|
|
3928
3985
|
"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."
|
|
3986
|
+
},
|
|
3987
|
+
"sourceTranscript": {
|
|
3988
|
+
"type": "object",
|
|
3989
|
+
"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.",
|
|
3990
|
+
"properties": {
|
|
3991
|
+
"documentId": {
|
|
3992
|
+
"type": "string",
|
|
3993
|
+
"description": "The id of a Stable Baseline document holding the meeting transcript/notes to design from."
|
|
3994
|
+
},
|
|
3995
|
+
"text": {
|
|
3996
|
+
"type": "string",
|
|
3997
|
+
"description": "The raw transcript text to design from (pasted). Provide this OR documentId, not both."
|
|
3998
|
+
}
|
|
3999
|
+
}
|
|
3929
4000
|
}
|
|
3930
4001
|
},
|
|
3931
4002
|
"required": [
|
|
@@ -4069,6 +4140,10 @@
|
|
|
4069
4140
|
"type": "string",
|
|
4070
4141
|
"description": "Optional URL of a reference image the component should match; the critic compares the render to it."
|
|
4071
4142
|
},
|
|
4143
|
+
"brandKitId": {
|
|
4144
|
+
"type": "string",
|
|
4145
|
+
"description": "Optional brand kit id (from listBrandKits) to theme the component. If omitted, the organisation's effective brand is used."
|
|
4146
|
+
},
|
|
4072
4147
|
"force": {
|
|
4073
4148
|
"type": "boolean",
|
|
4074
4149
|
"description": "Redesign even if a component with this key already exists (default false = reuse)."
|
|
@@ -4284,7 +4359,7 @@
|
|
|
4284
4359
|
"/tools/designDeckInWhiteboard": {
|
|
4285
4360
|
"post": {
|
|
4286
4361
|
"summary": "designDeckInWhiteboard",
|
|
4287
|
-
"description": "Create or refine a slide deck INSIDE an existing whiteboard by conversing with the AI design agent. Send a brief for a NEW deck, a change to an EXISTING one, or an answer to the agent's question. The agent builds a polished, on-brand deck and places it on the board; if the brief is ambiguous it asks ONE clarifying question (answer with the same sessionId). Returns immediately; poll getDeckReplyInWhiteboard for the result. Use for building or editing slide decks / presentations. WHITEBOARD IS REQUIRED: a deck always lives inside a whiteboard, so documentId (the whiteboard's id) is required. If you do NOT already have a whiteboard id, ASK THE USER which whiteboard they want the deck designed in — do NOT create a whiteboard automatically. Only call createWhiteboard first if the user explicitly asks for a brand-new board; otherwise use the id of the whiteboard they name. FIRST vs FOLLOW-UP: the first call (from nothing) builds; a follow-up call (an answer, a change, or a new instruction) passes the sessionId (or the deckId) plus the new message. kind:'deck' (default) is the premium on-brand HTML deck; kind:'express' builds the native, deterministic branded-executive deck directly on the whiteboard (faster, lower fidelity, one-shot, not conversational). COST + APPROVAL: a build costs 50 credits and an edit 10; a clarifying question is FREE. Call FIRST without confirm to get the exact cost plus the workspace balance, show it to the user, and only call again with confirm:true once they agree. The fee is auto-refunded if a turn produces no change or fails. Returns sessionId (the conversation), deckId (the deck), status, turnType, started, awaitingUser, needsConfirmation, insufficientCredits, and assistantMessage. Export the finished deck with exportFromWhiteboard.",
|
|
4362
|
+
"description": "Create or refine a slide deck INSIDE an existing whiteboard by conversing with the AI design agent. Send a brief for a NEW deck, a change to an EXISTING one, or an answer to the agent's question. The agent builds a polished, on-brand deck and places it on the board; if the brief is ambiguous it asks ONE clarifying question (answer with the same sessionId). Returns immediately; poll getDeckReplyInWhiteboard for the result. Use for building or editing slide decks / presentations. WHITEBOARD IS REQUIRED: a deck always lives inside a whiteboard, so documentId (the whiteboard's id) is required. If you do NOT already have a whiteboard id, ASK THE USER which whiteboard they want the deck designed in — do NOT create a whiteboard automatically. Only call createWhiteboard first if the user explicitly asks for a brand-new board; otherwise use the id of the whiteboard they name. FIRST vs FOLLOW-UP: the first call (from nothing) builds; a follow-up call (an answer, a change, or a new instruction) passes the sessionId (or the deckId) plus the new message. kind:'deck' (default) is the premium on-brand HTML deck; kind:'express' builds the native, deterministic branded-executive deck directly on the whiteboard (faster, lower fidelity, one-shot, not conversational). COST + APPROVAL: a build costs 50 credits and an edit 10; a clarifying question is FREE. GENERATED IMAGES are extra and OFF by default: decks are type-only unless the user asks for visuals, in which case set imageCount (5 credits each, ceiling scales with slide count and plan tier, max 10) and the exact total is quoted before anything is charged — exactly that many images are produced, and the image surcharge auto-refunds if the build cannot deliver them. ADVANCED DECK BUILDING (optional, OFF by default): set advancedDeckBuilding:true to build the deck over several rounds of redraft and review by a panel of design, brand, accessibility and copy reviewers instead of one composer pass. It usually raises design quality, but it is not a guarantee. It is much slower and it costs more: a standard build takes roughly 2 to 8 minutes, advanced deck building takes roughly 15 to 20 minutes, and it adds 15 credits per depth level on top of the turn fee (advancedDeckBuildingDepth is 1 to 3, default 3, so +45 credits, making a 50-credit build cost 95). Only turn it on when the user asks for the highest quality and accepts the wait and the cost. Call FIRST without confirm to get the exact cost plus the workspace balance, show it to the user, and only call again with confirm:true once they agree. The fee is auto-refunded if a turn produces no change or fails. Returns sessionId (the conversation), deckId (the deck), status, turnType, started, awaitingUser, needsConfirmation, insufficientCredits, slideCount + slideCountClamped (the target the conversation now carries, and whether it was reduced to the maximum), advancedDeckBuilding (whether advanced deck building is on for this conversation), advancedDeckBuildingStatus, and assistantMessage. Export the finished deck with exportFromWhiteboard.",
|
|
4288
4363
|
"operationId": "designDeckInWhiteboard",
|
|
4289
4364
|
"tags": [
|
|
4290
4365
|
"whiteboards"
|
|
@@ -4302,7 +4377,7 @@
|
|
|
4302
4377
|
},
|
|
4303
4378
|
"message": {
|
|
4304
4379
|
"type": "string",
|
|
4305
|
-
"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."
|
|
4380
|
+
"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."
|
|
4306
4381
|
},
|
|
4307
4382
|
"sessionId": {
|
|
4308
4383
|
"type": "string",
|
|
@@ -4332,7 +4407,19 @@
|
|
|
4332
4407
|
},
|
|
4333
4408
|
"slideCount": {
|
|
4334
4409
|
"type": "number",
|
|
4335
|
-
"description": "
|
|
4410
|
+
"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'). Anything above the 30-slide maximum is reduced to 30 and the reduction is stated back in the response. Omit ONLY when the user gave no count at all; the designer then chooses (typical 6 to 12)."
|
|
4411
|
+
},
|
|
4412
|
+
"imageCount": {
|
|
4413
|
+
"type": "number",
|
|
4414
|
+
"description": "How many AI-GENERATED images this turn may produce. DEFAULT IS 0 — decks are type-only unless the user asks for visuals. SET THIS when the user wants imagery: 'a cover image' → 1, 'a few images' → 2, 'image-led / very visual' → omit nothing and pass a higher number. Each image costs 5 extra credits, quoted upfront in the confirmation (base fee + images), and EXACTLY this many are produced — never more, never fewer (the image surcharge is auto-refunded if the build cannot deliver them). The ceiling scales with the deck (about one image per three slides, so a 30-slide deck tops out at 10) and with the plan tier; anything above the ceiling is reduced and the reduction is stated back. If omitted, the count is derived conservatively from the user's wording (silence = 0)."
|
|
4415
|
+
},
|
|
4416
|
+
"advancedDeckBuilding": {
|
|
4417
|
+
"type": "boolean",
|
|
4418
|
+
"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."
|
|
4419
|
+
},
|
|
4420
|
+
"advancedDeckBuildingDepth": {
|
|
4421
|
+
"type": "number",
|
|
4422
|
+
"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."
|
|
4336
4423
|
},
|
|
4337
4424
|
"attachments": {
|
|
4338
4425
|
"type": "array",
|
|
@@ -4356,6 +4443,10 @@
|
|
|
4356
4443
|
"name": {
|
|
4357
4444
|
"type": "string",
|
|
4358
4445
|
"description": "Optional human-readable name for the image."
|
|
4446
|
+
},
|
|
4447
|
+
"type": {
|
|
4448
|
+
"type": "string",
|
|
4449
|
+
"description": "Optional attachment type hint, passed through to the design worker."
|
|
4359
4450
|
}
|
|
4360
4451
|
}
|
|
4361
4452
|
}
|
|
@@ -4509,6 +4600,10 @@
|
|
|
4509
4600
|
"name": {
|
|
4510
4601
|
"type": "string",
|
|
4511
4602
|
"description": "Optional human-readable name for the image."
|
|
4603
|
+
},
|
|
4604
|
+
"type": {
|
|
4605
|
+
"type": "string",
|
|
4606
|
+
"description": "Optional attachment type hint, passed through to the design worker."
|
|
4512
4607
|
}
|
|
4513
4608
|
}
|
|
4514
4609
|
}
|
|
@@ -4604,7 +4699,7 @@
|
|
|
4604
4699
|
"/tools/getDeckReplyInWhiteboard": {
|
|
4605
4700
|
"post": {
|
|
4606
4701
|
"summary": "getDeckReplyInWhiteboard",
|
|
4607
|
-
"description": "Get the design agent's reply after calling designDeckInWhiteboard OR designIllustrationInWhiteboard: the status (thinking/building/ready) and EITHER the finished result (a deck's slide count + preview, or the placed illustration) OR a clarifying question to answer (call the SAME tool you started with, passing the sessionId + your answer). Poll until ready or a question appears. Give it the whiteboard documentId and the deckId (both returned by the tool you called). It returns the build status ('generating' while working, 'ready' when finished, 'failed' if it failed) plus, once ready, the slide count and a thumbnail image URL. IMPORTANT for the conversation: if the agent asked a CLARIFYING QUESTION instead of doing the work, this returns awaitingUser:true with pendingQuestion (and assistantMessage) — relay that question to the user, then call the SAME design tool again with the same sessionId and the user's answer as message to continue. It also returns the full conversation (history + status + pending question). A turn usually takes about
|
|
4702
|
+
"description": "Get the design agent's reply after calling designDeckInWhiteboard OR designIllustrationInWhiteboard: the status (thinking/building/ready) and EITHER the finished result (a deck's slide count + preview, or the placed illustration) OR a clarifying question to answer (call the SAME tool you started with, passing the sessionId + your answer). Poll until ready or a question appears. Give it the whiteboard documentId and the deckId (both returned by the tool you called). It returns the build status ('generating' while working, 'ready' when finished, 'failed' if it failed) plus, once ready, the slide count and a thumbnail image URL. IMPORTANT for the conversation: if the agent asked a CLARIFYING QUESTION instead of doing the work, this returns awaitingUser:true with pendingQuestion (and assistantMessage) — relay that question to the user, then call the SAME design tool again with the same sessionId and the user's answer as message to continue. It also returns the full conversation (history + status + pending question). While a turn is running it additionally returns live build state: stage, percent, feed (the agent's real per-step lines), slideTarget (the count it is building to), slides (the finished slides so far, each with a fetchable image url), partialHtml (the deck so far), and, when advanced deck building is on, advancedDeckBuildingProgress (the round-by-round reviewer scores; also emitted as the deprecated `jury` field for one release). Every one of those is optional and absent when there is nothing to report. A standard turn usually takes about 2 to 8 minutes, so poll every 15 to 30 seconds until it is 'ready' or awaitingUser is true; a turn running with advanced deck building takes roughly 15 to 20 minutes, so keep polling for that long before treating it as stuck. When ready, the deck or illustration has already been placed on the whiteboard; a deck can also be exported with exportFromWhiteboard. If a turn failed or produced no change, the user was not charged.",
|
|
4608
4703
|
"operationId": "getDeckReplyInWhiteboard",
|
|
4609
4704
|
"tags": [
|
|
4610
4705
|
"whiteboards"
|
|
@@ -4836,6 +4931,356 @@
|
|
|
4836
4931
|
}
|
|
4837
4932
|
}
|
|
4838
4933
|
},
|
|
4934
|
+
"/tools/startMeetingScribe": {
|
|
4935
|
+
"post": {
|
|
4936
|
+
"summary": "startMeetingScribe",
|
|
4937
|
+
"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.",
|
|
4938
|
+
"operationId": "startMeetingScribe",
|
|
4939
|
+
"tags": [
|
|
4940
|
+
"whiteboards"
|
|
4941
|
+
],
|
|
4942
|
+
"requestBody": {
|
|
4943
|
+
"required": false,
|
|
4944
|
+
"content": {
|
|
4945
|
+
"application/json": {
|
|
4946
|
+
"schema": {
|
|
4947
|
+
"type": "object",
|
|
4948
|
+
"properties": {
|
|
4949
|
+
"documentId": {
|
|
4950
|
+
"type": "string",
|
|
4951
|
+
"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."
|
|
4952
|
+
},
|
|
4953
|
+
"meetingUrl": {
|
|
4954
|
+
"type": "string",
|
|
4955
|
+
"description": "The meeting link to join: a Zoom, Google Meet, Microsoft Teams, or Webex URL (https only). Any other host is rejected."
|
|
4956
|
+
},
|
|
4957
|
+
"agenda": {
|
|
4958
|
+
"type": "array",
|
|
4959
|
+
"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.",
|
|
4960
|
+
"items": {
|
|
4961
|
+
"type": "object",
|
|
4962
|
+
"description": "One agenda item.",
|
|
4963
|
+
"properties": {
|
|
4964
|
+
"label": {
|
|
4965
|
+
"type": "string",
|
|
4966
|
+
"description": "The agenda item text."
|
|
4967
|
+
},
|
|
4968
|
+
"id": {
|
|
4969
|
+
"type": "string",
|
|
4970
|
+
"description": "Optional stable id; one is minted if omitted."
|
|
4971
|
+
},
|
|
4972
|
+
"status": {
|
|
4973
|
+
"type": "string",
|
|
4974
|
+
"enum": [
|
|
4975
|
+
"pending",
|
|
4976
|
+
"active",
|
|
4977
|
+
"done"
|
|
4978
|
+
],
|
|
4979
|
+
"description": "Optional starting status sticker. Default: pending."
|
|
4980
|
+
}
|
|
4981
|
+
},
|
|
4982
|
+
"required": [
|
|
4983
|
+
"label"
|
|
4984
|
+
]
|
|
4985
|
+
}
|
|
4986
|
+
},
|
|
4987
|
+
"settings": {
|
|
4988
|
+
"type": "object",
|
|
4989
|
+
"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)') }.",
|
|
4990
|
+
"additionalProperties": true
|
|
4991
|
+
},
|
|
4992
|
+
"confirm": {
|
|
4993
|
+
"type": "boolean",
|
|
4994
|
+
"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."
|
|
4995
|
+
}
|
|
4996
|
+
},
|
|
4997
|
+
"required": [
|
|
4998
|
+
"documentId",
|
|
4999
|
+
"meetingUrl"
|
|
5000
|
+
]
|
|
5001
|
+
}
|
|
5002
|
+
}
|
|
5003
|
+
}
|
|
5004
|
+
},
|
|
5005
|
+
"responses": {
|
|
5006
|
+
"200": {
|
|
5007
|
+
"description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
|
|
5008
|
+
"content": {
|
|
5009
|
+
"application/json": {
|
|
5010
|
+
"schema": {
|
|
5011
|
+
"type": "object",
|
|
5012
|
+
"additionalProperties": true
|
|
5013
|
+
}
|
|
5014
|
+
}
|
|
5015
|
+
}
|
|
5016
|
+
},
|
|
5017
|
+
"400": {
|
|
5018
|
+
"description": "Validation error.",
|
|
5019
|
+
"content": {
|
|
5020
|
+
"application/json": {
|
|
5021
|
+
"schema": {
|
|
5022
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
5023
|
+
}
|
|
5024
|
+
}
|
|
5025
|
+
}
|
|
5026
|
+
},
|
|
5027
|
+
"401": {
|
|
5028
|
+
"description": "Missing or invalid credentials.",
|
|
5029
|
+
"content": {
|
|
5030
|
+
"application/json": {
|
|
5031
|
+
"schema": {
|
|
5032
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
5033
|
+
}
|
|
5034
|
+
}
|
|
5035
|
+
}
|
|
5036
|
+
},
|
|
5037
|
+
"403": {
|
|
5038
|
+
"description": "Authenticated but lacking the required permission or feature flag.",
|
|
5039
|
+
"content": {
|
|
5040
|
+
"application/json": {
|
|
5041
|
+
"schema": {
|
|
5042
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
5043
|
+
}
|
|
5044
|
+
}
|
|
5045
|
+
}
|
|
5046
|
+
},
|
|
5047
|
+
"404": {
|
|
5048
|
+
"description": "Resource not found.",
|
|
5049
|
+
"content": {
|
|
5050
|
+
"application/json": {
|
|
5051
|
+
"schema": {
|
|
5052
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
5053
|
+
}
|
|
5054
|
+
}
|
|
5055
|
+
}
|
|
5056
|
+
},
|
|
5057
|
+
"422": {
|
|
5058
|
+
"description": "Body did not match the tool's input schema.",
|
|
5059
|
+
"content": {
|
|
5060
|
+
"application/json": {
|
|
5061
|
+
"schema": {
|
|
5062
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
5063
|
+
}
|
|
5064
|
+
}
|
|
5065
|
+
}
|
|
5066
|
+
},
|
|
5067
|
+
"500": {
|
|
5068
|
+
"description": "Server error.",
|
|
5069
|
+
"content": {
|
|
5070
|
+
"application/json": {
|
|
5071
|
+
"schema": {
|
|
5072
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
5073
|
+
}
|
|
5074
|
+
}
|
|
5075
|
+
}
|
|
5076
|
+
}
|
|
5077
|
+
}
|
|
5078
|
+
}
|
|
5079
|
+
},
|
|
5080
|
+
"/tools/getMeetingScribeStatus": {
|
|
5081
|
+
"post": {
|
|
5082
|
+
"summary": "getMeetingScribeStatus",
|
|
5083
|
+
"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).",
|
|
5084
|
+
"operationId": "getMeetingScribeStatus",
|
|
5085
|
+
"tags": [
|
|
5086
|
+
"whiteboards"
|
|
5087
|
+
],
|
|
5088
|
+
"requestBody": {
|
|
5089
|
+
"required": false,
|
|
5090
|
+
"content": {
|
|
5091
|
+
"application/json": {
|
|
5092
|
+
"schema": {
|
|
5093
|
+
"type": "object",
|
|
5094
|
+
"properties": {
|
|
5095
|
+
"sessionId": {
|
|
5096
|
+
"type": "string",
|
|
5097
|
+
"description": "The meeting scribe session to poll, as returned by startMeetingScribe."
|
|
5098
|
+
}
|
|
5099
|
+
},
|
|
5100
|
+
"required": [
|
|
5101
|
+
"sessionId"
|
|
5102
|
+
]
|
|
5103
|
+
}
|
|
5104
|
+
}
|
|
5105
|
+
}
|
|
5106
|
+
},
|
|
5107
|
+
"responses": {
|
|
5108
|
+
"200": {
|
|
5109
|
+
"description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
|
|
5110
|
+
"content": {
|
|
5111
|
+
"application/json": {
|
|
5112
|
+
"schema": {
|
|
5113
|
+
"type": "object",
|
|
5114
|
+
"additionalProperties": true
|
|
5115
|
+
}
|
|
5116
|
+
}
|
|
5117
|
+
}
|
|
5118
|
+
},
|
|
5119
|
+
"400": {
|
|
5120
|
+
"description": "Validation error.",
|
|
5121
|
+
"content": {
|
|
5122
|
+
"application/json": {
|
|
5123
|
+
"schema": {
|
|
5124
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
5125
|
+
}
|
|
5126
|
+
}
|
|
5127
|
+
}
|
|
5128
|
+
},
|
|
5129
|
+
"401": {
|
|
5130
|
+
"description": "Missing or invalid credentials.",
|
|
5131
|
+
"content": {
|
|
5132
|
+
"application/json": {
|
|
5133
|
+
"schema": {
|
|
5134
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
5135
|
+
}
|
|
5136
|
+
}
|
|
5137
|
+
}
|
|
5138
|
+
},
|
|
5139
|
+
"403": {
|
|
5140
|
+
"description": "Authenticated but lacking the required permission or feature flag.",
|
|
5141
|
+
"content": {
|
|
5142
|
+
"application/json": {
|
|
5143
|
+
"schema": {
|
|
5144
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
5145
|
+
}
|
|
5146
|
+
}
|
|
5147
|
+
}
|
|
5148
|
+
},
|
|
5149
|
+
"404": {
|
|
5150
|
+
"description": "Resource not found.",
|
|
5151
|
+
"content": {
|
|
5152
|
+
"application/json": {
|
|
5153
|
+
"schema": {
|
|
5154
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
5155
|
+
}
|
|
5156
|
+
}
|
|
5157
|
+
}
|
|
5158
|
+
},
|
|
5159
|
+
"422": {
|
|
5160
|
+
"description": "Body did not match the tool's input schema.",
|
|
5161
|
+
"content": {
|
|
5162
|
+
"application/json": {
|
|
5163
|
+
"schema": {
|
|
5164
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
5165
|
+
}
|
|
5166
|
+
}
|
|
5167
|
+
}
|
|
5168
|
+
},
|
|
5169
|
+
"500": {
|
|
5170
|
+
"description": "Server error.",
|
|
5171
|
+
"content": {
|
|
5172
|
+
"application/json": {
|
|
5173
|
+
"schema": {
|
|
5174
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
5175
|
+
}
|
|
5176
|
+
}
|
|
5177
|
+
}
|
|
5178
|
+
}
|
|
5179
|
+
}
|
|
5180
|
+
}
|
|
5181
|
+
},
|
|
5182
|
+
"/tools/stopMeetingScribe": {
|
|
5183
|
+
"post": {
|
|
5184
|
+
"summary": "stopMeetingScribe",
|
|
5185
|
+
"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.",
|
|
5186
|
+
"operationId": "stopMeetingScribe",
|
|
5187
|
+
"tags": [
|
|
5188
|
+
"whiteboards"
|
|
5189
|
+
],
|
|
5190
|
+
"requestBody": {
|
|
5191
|
+
"required": false,
|
|
5192
|
+
"content": {
|
|
5193
|
+
"application/json": {
|
|
5194
|
+
"schema": {
|
|
5195
|
+
"type": "object",
|
|
5196
|
+
"properties": {
|
|
5197
|
+
"sessionId": {
|
|
5198
|
+
"type": "string",
|
|
5199
|
+
"description": "The meeting scribe session to stop, as returned by startMeetingScribe."
|
|
5200
|
+
}
|
|
5201
|
+
},
|
|
5202
|
+
"required": [
|
|
5203
|
+
"sessionId"
|
|
5204
|
+
]
|
|
5205
|
+
}
|
|
5206
|
+
}
|
|
5207
|
+
}
|
|
5208
|
+
},
|
|
5209
|
+
"responses": {
|
|
5210
|
+
"200": {
|
|
5211
|
+
"description": "Tool result (shape varies per tool — refer to the tool's docs for the exact return value).",
|
|
5212
|
+
"content": {
|
|
5213
|
+
"application/json": {
|
|
5214
|
+
"schema": {
|
|
5215
|
+
"type": "object",
|
|
5216
|
+
"additionalProperties": true
|
|
5217
|
+
}
|
|
5218
|
+
}
|
|
5219
|
+
}
|
|
5220
|
+
},
|
|
5221
|
+
"400": {
|
|
5222
|
+
"description": "Validation error.",
|
|
5223
|
+
"content": {
|
|
5224
|
+
"application/json": {
|
|
5225
|
+
"schema": {
|
|
5226
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
5227
|
+
}
|
|
5228
|
+
}
|
|
5229
|
+
}
|
|
5230
|
+
},
|
|
5231
|
+
"401": {
|
|
5232
|
+
"description": "Missing or invalid credentials.",
|
|
5233
|
+
"content": {
|
|
5234
|
+
"application/json": {
|
|
5235
|
+
"schema": {
|
|
5236
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
5237
|
+
}
|
|
5238
|
+
}
|
|
5239
|
+
}
|
|
5240
|
+
},
|
|
5241
|
+
"403": {
|
|
5242
|
+
"description": "Authenticated but lacking the required permission or feature flag.",
|
|
5243
|
+
"content": {
|
|
5244
|
+
"application/json": {
|
|
5245
|
+
"schema": {
|
|
5246
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
5247
|
+
}
|
|
5248
|
+
}
|
|
5249
|
+
}
|
|
5250
|
+
},
|
|
5251
|
+
"404": {
|
|
5252
|
+
"description": "Resource not found.",
|
|
5253
|
+
"content": {
|
|
5254
|
+
"application/json": {
|
|
5255
|
+
"schema": {
|
|
5256
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
5257
|
+
}
|
|
5258
|
+
}
|
|
5259
|
+
}
|
|
5260
|
+
},
|
|
5261
|
+
"422": {
|
|
5262
|
+
"description": "Body did not match the tool's input schema.",
|
|
5263
|
+
"content": {
|
|
5264
|
+
"application/json": {
|
|
5265
|
+
"schema": {
|
|
5266
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
5267
|
+
}
|
|
5268
|
+
}
|
|
5269
|
+
}
|
|
5270
|
+
},
|
|
5271
|
+
"500": {
|
|
5272
|
+
"description": "Server error.",
|
|
5273
|
+
"content": {
|
|
5274
|
+
"application/json": {
|
|
5275
|
+
"schema": {
|
|
5276
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
5277
|
+
}
|
|
5278
|
+
}
|
|
5279
|
+
}
|
|
5280
|
+
}
|
|
5281
|
+
}
|
|
5282
|
+
}
|
|
5283
|
+
},
|
|
4839
5284
|
"/tools/createWhiteboard": {
|
|
4840
5285
|
"post": {
|
|
4841
5286
|
"summary": "createWhiteboard",
|
|
@@ -5062,8 +5507,13 @@
|
|
|
5062
5507
|
"schema": {
|
|
5063
5508
|
"type": "object",
|
|
5064
5509
|
"properties": {
|
|
5510
|
+
"projectId": {
|
|
5511
|
+
"type": "string",
|
|
5512
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
5513
|
+
},
|
|
5065
5514
|
"documentId": {
|
|
5066
|
-
"type": "string"
|
|
5515
|
+
"type": "string",
|
|
5516
|
+
"description": "Accepts either the UUID or the friendly id (e.g. WBD-12); friendly ids are resolved within your organisation."
|
|
5067
5517
|
},
|
|
5068
5518
|
"includeElements": {
|
|
5069
5519
|
"type": "boolean",
|
|
@@ -5167,6 +5617,10 @@
|
|
|
5167
5617
|
"schema": {
|
|
5168
5618
|
"type": "object",
|
|
5169
5619
|
"properties": {
|
|
5620
|
+
"projectId": {
|
|
5621
|
+
"type": "string",
|
|
5622
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
5623
|
+
},
|
|
5170
5624
|
"documentId": {
|
|
5171
5625
|
"type": "string"
|
|
5172
5626
|
},
|
|
@@ -5307,6 +5761,10 @@
|
|
|
5307
5761
|
"schema": {
|
|
5308
5762
|
"type": "object",
|
|
5309
5763
|
"properties": {
|
|
5764
|
+
"projectId": {
|
|
5765
|
+
"type": "string",
|
|
5766
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
5767
|
+
},
|
|
5310
5768
|
"documentId": {
|
|
5311
5769
|
"type": "string"
|
|
5312
5770
|
},
|
|
@@ -5805,6 +6263,15 @@
|
|
|
5805
6263
|
"locked": {
|
|
5806
6264
|
"type": "boolean",
|
|
5807
6265
|
"description": "Lock the placed image so it cannot be moved, resized, or deleted by hand (e.g. a deck-owned framed slide image that changes only via the deck conversation). Defaults to false."
|
|
6266
|
+
},
|
|
6267
|
+
"nlDescription": {
|
|
6268
|
+
"type": "string",
|
|
6269
|
+
"description": "Optional plain-language description of the image, stored on the element for accessibility and so agents reading the board later know what it depicts."
|
|
6270
|
+
},
|
|
6271
|
+
"customData": {
|
|
6272
|
+
"type": "object",
|
|
6273
|
+
"additionalProperties": true,
|
|
6274
|
+
"description": "Arbitrary Excalidraw customData stored on the element (e.g. { deckId } so a board image resolves back to its source deck). Merged with any builder-set customData."
|
|
5808
6275
|
}
|
|
5809
6276
|
},
|
|
5810
6277
|
"required": [
|
|
@@ -5892,7 +6359,7 @@
|
|
|
5892
6359
|
"/tools/insertWhiteboardDiagram": {
|
|
5893
6360
|
"post": {
|
|
5894
6361
|
"summary": "insertWhiteboardDiagram",
|
|
5895
|
-
"description": "Insert a real DIAGRAM (BPMN, Diagrams-as-Code / any DSL: mermaid, d2, plantuml, graphviz, …)
|
|
6362
|
+
"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
6363
|
"operationId": "insertWhiteboardDiagram",
|
|
5897
6364
|
"tags": [
|
|
5898
6365
|
"whiteboards"
|
|
@@ -5922,7 +6389,7 @@
|
|
|
5922
6389
|
},
|
|
5923
6390
|
"width": {
|
|
5924
6391
|
"type": "number",
|
|
5925
|
-
"description": "Display width in px (aspect ratio preserved).
|
|
6392
|
+
"description": "Display width in px (aspect ratio preserved). Auto-size caps at 480px; an explicit width is honoured up to 1200px."
|
|
5926
6393
|
},
|
|
5927
6394
|
"height": {
|
|
5928
6395
|
"type": "number",
|
|
@@ -5930,11 +6397,11 @@
|
|
|
5930
6397
|
},
|
|
5931
6398
|
"x": {
|
|
5932
6399
|
"type": "number",
|
|
5933
|
-
"description": "Top-left x on the canvas. Omit to auto-place."
|
|
6400
|
+
"description": "Top-left x on the canvas. Omit to auto-place (or to keep the existing position when updateElementId is given)."
|
|
5934
6401
|
},
|
|
5935
6402
|
"y": {
|
|
5936
6403
|
"type": "number",
|
|
5937
|
-
"description": "Top-left y on the canvas. Omit to auto-place."
|
|
6404
|
+
"description": "Top-left y on the canvas. Omit to auto-place (or to keep the existing position when updateElementId is given)."
|
|
5938
6405
|
},
|
|
5939
6406
|
"align": {
|
|
5940
6407
|
"type": "string",
|
|
@@ -5944,6 +6411,17 @@
|
|
|
5944
6411
|
"right"
|
|
5945
6412
|
],
|
|
5946
6413
|
"description": "Horizontal alignment relative to existing content (placed below it). Ignored if x/y given."
|
|
6414
|
+
},
|
|
6415
|
+
"updateElementId": {
|
|
6416
|
+
"type": "string",
|
|
6417
|
+
"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."
|
|
6418
|
+
},
|
|
6419
|
+
"fit": {
|
|
6420
|
+
"type": "string",
|
|
6421
|
+
"enum": [
|
|
6422
|
+
"contain"
|
|
6423
|
+
],
|
|
6424
|
+
"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
6425
|
}
|
|
5948
6426
|
},
|
|
5949
6427
|
"required": [
|
|
@@ -6188,6 +6666,10 @@
|
|
|
6188
6666
|
"schema": {
|
|
6189
6667
|
"type": "object",
|
|
6190
6668
|
"properties": {
|
|
6669
|
+
"projectId": {
|
|
6670
|
+
"type": "string",
|
|
6671
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
6672
|
+
},
|
|
6191
6673
|
"documentId": {
|
|
6192
6674
|
"type": "string",
|
|
6193
6675
|
"description": "The whiteboard's documentId."
|
|
@@ -6441,9 +6923,13 @@
|
|
|
6441
6923
|
"schema": {
|
|
6442
6924
|
"type": "object",
|
|
6443
6925
|
"properties": {
|
|
6926
|
+
"projectId": {
|
|
6927
|
+
"type": "string",
|
|
6928
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
6929
|
+
},
|
|
6444
6930
|
"documentId": {
|
|
6445
6931
|
"type": "string",
|
|
6446
|
-
"description": "The whiteboard's documentId."
|
|
6932
|
+
"description": "The whiteboard's documentId. Accepts either the UUID or the friendly id (e.g. WBD-12); friendly ids are resolved within your organisation."
|
|
6447
6933
|
},
|
|
6448
6934
|
"elementIds": {
|
|
6449
6935
|
"type": "array",
|
|
@@ -6593,6 +7079,10 @@
|
|
|
6593
7079
|
"properties": {
|
|
6594
7080
|
"documentId": {
|
|
6595
7081
|
"type": "string"
|
|
7082
|
+
},
|
|
7083
|
+
"projectId": {
|
|
7084
|
+
"type": "string",
|
|
7085
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Ignored when documentId is a UUID."
|
|
6596
7086
|
}
|
|
6597
7087
|
},
|
|
6598
7088
|
"required": [
|
|
@@ -6809,7 +7299,7 @@
|
|
|
6809
7299
|
"/tools/getDiagramImage": {
|
|
6810
7300
|
"post": {
|
|
6811
7301
|
"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.",
|
|
7302
|
+
"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
7303
|
"operationId": "getDiagramImage",
|
|
6814
7304
|
"tags": [
|
|
6815
7305
|
"diagrams"
|
|
@@ -7043,7 +7533,7 @@
|
|
|
7043
7533
|
"/tools/reorderDocuments": {
|
|
7044
7534
|
"post": {
|
|
7045
7535
|
"summary": "reorderDocuments",
|
|
7046
|
-
"description": "
|
|
7536
|
+
"description": "MOVE documents between folders and/or reorder them — the batch filing tool. Pass [{documentId, position, folderId?}, ...]: `position` is a non-negative integer (usually renumber siblings sequentially as 0, 1, 2…), and the optional per-item `folderId` MOVES that document into the given folder (use null to move it to the project root; omit it to leave the document where it is). Use this to reorganise a project — file loose documents into subfolders, restructure a folder tree, or reorder siblings — in one call. Filing is metadata only: it does NOT bump the document version and does NOT create a version-history snapshot, so tidying folders never shows up as a content revision. A bad folderId fails the whole call rather than half-applying it. For a single document you can also use editDocument({documentId, folderId, position}), which behaves identically (and likewise creates no version when only the filing changes).",
|
|
7047
7537
|
"operationId": "reorderDocuments",
|
|
7048
7538
|
"tags": [
|
|
7049
7539
|
"documents"
|
|
@@ -7057,7 +7547,7 @@
|
|
|
7057
7547
|
"properties": {
|
|
7058
7548
|
"items": {
|
|
7059
7549
|
"type": "array",
|
|
7060
|
-
"description": "
|
|
7550
|
+
"description": "Documents to file. All must belong to the same project (a batch spanning projects is rejected).",
|
|
7061
7551
|
"items": {
|
|
7062
7552
|
"type": "object",
|
|
7063
7553
|
"properties": {
|
|
@@ -7065,7 +7555,15 @@
|
|
|
7065
7555
|
"type": "string"
|
|
7066
7556
|
},
|
|
7067
7557
|
"position": {
|
|
7068
|
-
"type": "number"
|
|
7558
|
+
"type": "number",
|
|
7559
|
+
"description": "Sort position among siblings. Non-negative integer."
|
|
7560
|
+
},
|
|
7561
|
+
"folderId": {
|
|
7562
|
+
"type": [
|
|
7563
|
+
"string",
|
|
7564
|
+
"null"
|
|
7565
|
+
],
|
|
7566
|
+
"description": "Optional. MOVE the document into this folder; null moves it to the project root. Omit to leave its current folder untouched. The folder must exist and belong to the same project."
|
|
7069
7567
|
}
|
|
7070
7568
|
},
|
|
7071
7569
|
"required": [
|
|
@@ -7173,8 +7671,13 @@
|
|
|
7173
7671
|
"schema": {
|
|
7174
7672
|
"type": "object",
|
|
7175
7673
|
"properties": {
|
|
7674
|
+
"projectId": {
|
|
7675
|
+
"type": "string",
|
|
7676
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
7677
|
+
},
|
|
7176
7678
|
"documentId": {
|
|
7177
|
-
"type": "string"
|
|
7679
|
+
"type": "string",
|
|
7680
|
+
"description": "Accepts either the UUID or the friendly id (e.g. DOC-815); friendly ids are resolved within your organisation."
|
|
7178
7681
|
},
|
|
7179
7682
|
"versionNumber": {
|
|
7180
7683
|
"type": "number",
|
|
@@ -7411,6 +7914,10 @@
|
|
|
7411
7914
|
"schema": {
|
|
7412
7915
|
"type": "object",
|
|
7413
7916
|
"properties": {
|
|
7917
|
+
"projectId": {
|
|
7918
|
+
"type": "string",
|
|
7919
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
7920
|
+
},
|
|
7414
7921
|
"documentId": {
|
|
7415
7922
|
"type": "string"
|
|
7416
7923
|
},
|
|
@@ -7526,12 +8033,16 @@
|
|
|
7526
8033
|
"schema": {
|
|
7527
8034
|
"type": "object",
|
|
7528
8035
|
"properties": {
|
|
8036
|
+
"projectId": {
|
|
8037
|
+
"type": "string",
|
|
8038
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
8039
|
+
},
|
|
7529
8040
|
"documentId": {
|
|
7530
8041
|
"type": "string"
|
|
7531
8042
|
},
|
|
7532
8043
|
"documentVersionTimestamp": {
|
|
7533
8044
|
"type": "number",
|
|
7534
|
-
"description": "
|
|
8045
|
+
"description": "Optimistic-lock token: the document's versionTimestamp from getDocument() or any mutating tool's response. (Alias accepted: versionTimestamp.)"
|
|
7535
8046
|
},
|
|
7536
8047
|
"imageBase64": {
|
|
7537
8048
|
"type": "string",
|
|
@@ -7588,7 +8099,6 @@
|
|
|
7588
8099
|
},
|
|
7589
8100
|
"required": [
|
|
7590
8101
|
"documentId",
|
|
7591
|
-
"documentVersionTimestamp",
|
|
7592
8102
|
"nlDescription",
|
|
7593
8103
|
"caption"
|
|
7594
8104
|
]
|
|
@@ -7674,7 +8184,7 @@
|
|
|
7674
8184
|
"/tools/updateImageInDocument": {
|
|
7675
8185
|
"post": {
|
|
7676
8186
|
"summary": "updateImageInDocument",
|
|
7677
|
-
"description": "Update image metadata (alt, caption, dimensions, alignment). Requires
|
|
8187
|
+
"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
8188
|
"operationId": "updateImageInDocument",
|
|
7679
8189
|
"tags": [
|
|
7680
8190
|
"images"
|
|
@@ -7692,7 +8202,7 @@
|
|
|
7692
8202
|
},
|
|
7693
8203
|
"documentVersionTimestamp": {
|
|
7694
8204
|
"type": "number",
|
|
7695
|
-
"description": "
|
|
8205
|
+
"description": "Optimistic-lock token: the document's versionTimestamp from getDocument() or any mutating tool's response. (Alias accepted: versionTimestamp.)"
|
|
7696
8206
|
},
|
|
7697
8207
|
"alt": {
|
|
7698
8208
|
"type": "string",
|
|
@@ -7725,8 +8235,7 @@
|
|
|
7725
8235
|
}
|
|
7726
8236
|
},
|
|
7727
8237
|
"required": [
|
|
7728
|
-
"imageId"
|
|
7729
|
-
"documentVersionTimestamp"
|
|
8238
|
+
"imageId"
|
|
7730
8239
|
]
|
|
7731
8240
|
}
|
|
7732
8241
|
}
|
|
@@ -7924,6 +8433,10 @@
|
|
|
7924
8433
|
"schema": {
|
|
7925
8434
|
"type": "object",
|
|
7926
8435
|
"properties": {
|
|
8436
|
+
"projectId": {
|
|
8437
|
+
"type": "string",
|
|
8438
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
8439
|
+
},
|
|
7927
8440
|
"documentId": {
|
|
7928
8441
|
"type": "string"
|
|
7929
8442
|
},
|
|
@@ -8034,6 +8547,10 @@
|
|
|
8034
8547
|
"schema": {
|
|
8035
8548
|
"type": "object",
|
|
8036
8549
|
"properties": {
|
|
8550
|
+
"projectId": {
|
|
8551
|
+
"type": "string",
|
|
8552
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
8553
|
+
},
|
|
8037
8554
|
"documentId": {
|
|
8038
8555
|
"type": "string"
|
|
8039
8556
|
},
|
|
@@ -8652,8 +9169,13 @@
|
|
|
8652
9169
|
"schema": {
|
|
8653
9170
|
"type": "object",
|
|
8654
9171
|
"properties": {
|
|
9172
|
+
"projectId": {
|
|
9173
|
+
"type": "string",
|
|
9174
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
9175
|
+
},
|
|
8655
9176
|
"improvementId": {
|
|
8656
|
-
"type": "string"
|
|
9177
|
+
"type": "string",
|
|
9178
|
+
"description": "Accepts either the UUID or the friendly id (e.g. IMP-42); friendly ids are resolved within your organisation."
|
|
8657
9179
|
}
|
|
8658
9180
|
},
|
|
8659
9181
|
"required": [
|
|
@@ -8741,7 +9263,7 @@
|
|
|
8741
9263
|
"/tools/createImprovement": {
|
|
8742
9264
|
"post": {
|
|
8743
9265
|
"summary": "createImprovement",
|
|
8744
|
-
"description": "Create an improvement item in a project. Requires projectId and title. Auto-assigns friendly ID.",
|
|
9266
|
+
"description": "Create an improvement item in a project. Requires projectId and title. Auto-assigns friendly ID. Accepts every field updateImprovement accepts, so an item can be created complete in one call rather than create-then-update.",
|
|
8745
9267
|
"operationId": "createImprovement",
|
|
8746
9268
|
"tags": [
|
|
8747
9269
|
"improvements"
|
|
@@ -8761,7 +9283,7 @@
|
|
|
8761
9283
|
},
|
|
8762
9284
|
"type": {
|
|
8763
9285
|
"type": "string",
|
|
8764
|
-
"description": "Type. Default: enhancement. Valid values: feature, bug, tech_debt, architecture_gap, documentation_gap, risk, enhancement, task. Setting type='task' makes the row a task (TAS- prefix); any other type makes it a non-task improvement (IMP- prefix)."
|
|
9286
|
+
"description": "Type. Default: enhancement. Valid values: feature, bug, tech_debt, architecture_gap, documentation_gap, risk, enhancement, task. Despite the tool's name there is no 'improvement' value — pass it and it is accepted as an alias for 'enhancement', which is also the default. Setting type='task' makes the row a task (TAS- prefix); any other type makes it a non-task improvement (IMP- prefix)."
|
|
8765
9287
|
},
|
|
8766
9288
|
"priority": {
|
|
8767
9289
|
"type": "string",
|
|
@@ -8806,10 +9328,22 @@
|
|
|
8806
9328
|
"properties": {
|
|
8807
9329
|
"id": {
|
|
8808
9330
|
"type": "string",
|
|
8809
|
-
"description": "Optional — server mints one if omitted. Preserve on edits."
|
|
9331
|
+
"description": "Optional — server mints one if omitted. Preserve on edits."
|
|
9332
|
+
},
|
|
9333
|
+
"text": {
|
|
9334
|
+
"type": "string"
|
|
9335
|
+
},
|
|
9336
|
+
"updated_at": {
|
|
9337
|
+
"type": "string",
|
|
9338
|
+
"description": "Server-stamped. Echo back unchanged; ignored on new rows."
|
|
9339
|
+
},
|
|
9340
|
+
"updated_by": {
|
|
9341
|
+
"type": "string",
|
|
9342
|
+
"description": "Server-stamped user id. Echo back unchanged."
|
|
8810
9343
|
},
|
|
8811
|
-
"
|
|
8812
|
-
"type": "string"
|
|
9344
|
+
"updated_by_credential_name": {
|
|
9345
|
+
"type": "string",
|
|
9346
|
+
"description": "Server-stamped credential label. Echo back unchanged."
|
|
8813
9347
|
}
|
|
8814
9348
|
},
|
|
8815
9349
|
"required": [
|
|
@@ -8837,6 +9371,30 @@
|
|
|
8837
9371
|
"completed": {
|
|
8838
9372
|
"type": "boolean",
|
|
8839
9373
|
"description": "true = ticked, false/omitted = not done. Server stamps timestamp + actor."
|
|
9374
|
+
},
|
|
9375
|
+
"completed_at": {
|
|
9376
|
+
"type": "string",
|
|
9377
|
+
"description": "Server-stamped ISO timestamp. Prefer `completed`; an explicit value here wins if both are sent."
|
|
9378
|
+
},
|
|
9379
|
+
"completed_by": {
|
|
9380
|
+
"type": "string",
|
|
9381
|
+
"description": "Server-stamped user id. Echo back unchanged."
|
|
9382
|
+
},
|
|
9383
|
+
"completed_by_credential_name": {
|
|
9384
|
+
"type": "string",
|
|
9385
|
+
"description": "Server-stamped credential label. Echo back unchanged."
|
|
9386
|
+
},
|
|
9387
|
+
"updated_at": {
|
|
9388
|
+
"type": "string",
|
|
9389
|
+
"description": "Server-stamped. Echo back unchanged; ignored on new rows."
|
|
9390
|
+
},
|
|
9391
|
+
"updated_by": {
|
|
9392
|
+
"type": "string",
|
|
9393
|
+
"description": "Server-stamped user id. Echo back unchanged."
|
|
9394
|
+
},
|
|
9395
|
+
"updated_by_credential_name": {
|
|
9396
|
+
"type": "string",
|
|
9397
|
+
"description": "Server-stamped credential label. Echo back unchanged."
|
|
8840
9398
|
}
|
|
8841
9399
|
},
|
|
8842
9400
|
"required": [
|
|
@@ -8948,6 +9506,23 @@
|
|
|
8948
9506
|
"percent_complete": {
|
|
8949
9507
|
"type": "number",
|
|
8950
9508
|
"description": "Progress percentage (0-100). Null means not tracked."
|
|
9509
|
+
},
|
|
9510
|
+
"source_channel": {
|
|
9511
|
+
"type": "string"
|
|
9512
|
+
},
|
|
9513
|
+
"impacted_repositories": {
|
|
9514
|
+
"type": "array",
|
|
9515
|
+
"items": {
|
|
9516
|
+
"type": "string"
|
|
9517
|
+
}
|
|
9518
|
+
},
|
|
9519
|
+
"relationships": {
|
|
9520
|
+
"type": "object",
|
|
9521
|
+
"description": "Free-form JSON for logical links: blocks, blocked_by, duplicates, supersedes, relates_to (arrays of item IDs)."
|
|
9522
|
+
},
|
|
9523
|
+
"metadata": {
|
|
9524
|
+
"type": "object",
|
|
9525
|
+
"description": "Free-form JSON stored alongside the item. On updateImprovement this MERGES rather than replaces."
|
|
8951
9526
|
}
|
|
8952
9527
|
},
|
|
8953
9528
|
"required": [
|
|
@@ -9036,7 +9611,7 @@
|
|
|
9036
9611
|
"/tools/updateImprovement": {
|
|
9037
9612
|
"post": {
|
|
9038
9613
|
"summary": "updateImprovement",
|
|
9039
|
-
"description": "Update an improvement (or a task — tasks share this row, but prefer the symmetric updateTask alias when working from getTask). Supports the full field set including `checklist` (tick-boxes with due dates + completion attribution) and `acceptance_criteria` (objects with per-row updated_by/at attribution). Requires versionTimestamp from getImprovement for optimistic locking.
|
|
9614
|
+
"description": "Update an improvement (or a task — tasks share this row, but prefer the symmetric updateTask alias when working from getTask). Supports the full field set including `checklist` (tick-boxes with due dates + completion attribution) and `acceptance_criteria` (objects with per-row updated_by/at attribution). Requires versionTimestamp from getImprovement for optimistic locking. Statuses are captured / in_progress / blocked / done / rejected / deferred, and FOUR of those are CLOSED: blocked, done, rejected, deferred. Entering one needs its comment (blocked needs blocked_comment, rejected needs rejection_comment, done needs completion_comment); leaving one for an open status needs reopened_comment — including blocked -> in_progress, which surprises people because `blocked` does not sound terminal. `metadata` MERGES into what is stored (null on a key deletes it); pass metadata_replace:true to overwrite the object wholesale. Assignment: pass `owner_id=<uuid>` to assign to a user, `owner_team_id=<uuid>` to assign to a team (mutually exclusive — a DB CHECK constraint enforces this). To unassign, pass `owner_id=null` AND `owner_team_id=null`. To switch from a user owner to a team owner, send `owner_id=null, owner_team_id=<uuid>` in the SAME call (sending only one side leaves the stale value and triggers the XOR check). Use listAssignablePrincipals or listTeams to discover valid IDs.",
|
|
9040
9615
|
"operationId": "updateImprovement",
|
|
9041
9616
|
"tags": [
|
|
9042
9617
|
"improvements"
|
|
@@ -9048,6 +9623,10 @@
|
|
|
9048
9623
|
"schema": {
|
|
9049
9624
|
"type": "object",
|
|
9050
9625
|
"properties": {
|
|
9626
|
+
"projectId": {
|
|
9627
|
+
"type": "string",
|
|
9628
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
9629
|
+
},
|
|
9051
9630
|
"improvementId": {
|
|
9052
9631
|
"type": "string"
|
|
9053
9632
|
},
|
|
@@ -9129,6 +9708,18 @@
|
|
|
9129
9708
|
},
|
|
9130
9709
|
"text": {
|
|
9131
9710
|
"type": "string"
|
|
9711
|
+
},
|
|
9712
|
+
"updated_at": {
|
|
9713
|
+
"type": "string",
|
|
9714
|
+
"description": "Server-stamped. Echo back unchanged; ignored on new rows."
|
|
9715
|
+
},
|
|
9716
|
+
"updated_by": {
|
|
9717
|
+
"type": "string",
|
|
9718
|
+
"description": "Server-stamped user id. Echo back unchanged."
|
|
9719
|
+
},
|
|
9720
|
+
"updated_by_credential_name": {
|
|
9721
|
+
"type": "string",
|
|
9722
|
+
"description": "Server-stamped credential label. Echo back unchanged."
|
|
9132
9723
|
}
|
|
9133
9724
|
},
|
|
9134
9725
|
"required": [
|
|
@@ -9156,6 +9747,30 @@
|
|
|
9156
9747
|
"completed": {
|
|
9157
9748
|
"type": "boolean",
|
|
9158
9749
|
"description": "true = ticked, false/omitted = not done. Server stamps timestamp + actor."
|
|
9750
|
+
},
|
|
9751
|
+
"completed_at": {
|
|
9752
|
+
"type": "string",
|
|
9753
|
+
"description": "Server-stamped ISO timestamp. Prefer `completed`; an explicit value here wins if both are sent."
|
|
9754
|
+
},
|
|
9755
|
+
"completed_by": {
|
|
9756
|
+
"type": "string",
|
|
9757
|
+
"description": "Server-stamped user id. Echo back unchanged."
|
|
9758
|
+
},
|
|
9759
|
+
"completed_by_credential_name": {
|
|
9760
|
+
"type": "string",
|
|
9761
|
+
"description": "Server-stamped credential label. Echo back unchanged."
|
|
9762
|
+
},
|
|
9763
|
+
"updated_at": {
|
|
9764
|
+
"type": "string",
|
|
9765
|
+
"description": "Server-stamped. Echo back unchanged; ignored on new rows."
|
|
9766
|
+
},
|
|
9767
|
+
"updated_by": {
|
|
9768
|
+
"type": "string",
|
|
9769
|
+
"description": "Server-stamped user id. Echo back unchanged."
|
|
9770
|
+
},
|
|
9771
|
+
"updated_by_credential_name": {
|
|
9772
|
+
"type": "string",
|
|
9773
|
+
"description": "Server-stamped credential label. Echo back unchanged."
|
|
9159
9774
|
}
|
|
9160
9775
|
},
|
|
9161
9776
|
"required": [
|
|
@@ -9253,14 +9868,19 @@
|
|
|
9253
9868
|
},
|
|
9254
9869
|
"reopened_comment": {
|
|
9255
9870
|
"type": "string",
|
|
9256
|
-
"description": "Required when
|
|
9871
|
+
"description": "Required when moving OUT of a closed status. The closed set is blocked, done, rejected and deferred — note that `blocked` counts as closed, so blocked -> in_progress needs this comment."
|
|
9257
9872
|
},
|
|
9258
9873
|
"relationships": {
|
|
9259
9874
|
"type": "object",
|
|
9260
|
-
"description": "Free-form JSON for logical links: blocks, blocked_by, duplicates, supersedes, relates_to (arrays of item IDs)."
|
|
9875
|
+
"description": "Free-form JSON for logical links: blocks, blocked_by, duplicates, supersedes, relates_to (arrays of item IDs). REPLACES the stored object wholesale — read it first and send the complete set."
|
|
9261
9876
|
},
|
|
9262
9877
|
"metadata": {
|
|
9263
|
-
"type": "object"
|
|
9878
|
+
"type": "object",
|
|
9879
|
+
"description": "Free-form JSON. MERGES into the stored object key by key: keys you don't send are left alone, and sending a key with value null deletes it. Send metadata_replace:true to overwrite the whole object instead. (Merging is the default so a partial write can never destroy a sibling key written by another actor.)"
|
|
9880
|
+
},
|
|
9881
|
+
"metadata_replace": {
|
|
9882
|
+
"type": "boolean",
|
|
9883
|
+
"description": "Opt out of the metadata merge: true means the object you send REPLACES everything stored, deleting any key you omit. Default false."
|
|
9264
9884
|
},
|
|
9265
9885
|
"plan_id": {
|
|
9266
9886
|
"type": "string",
|
|
@@ -9383,6 +10003,10 @@
|
|
|
9383
10003
|
"schema": {
|
|
9384
10004
|
"type": "object",
|
|
9385
10005
|
"properties": {
|
|
10006
|
+
"projectId": {
|
|
10007
|
+
"type": "string",
|
|
10008
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
10009
|
+
},
|
|
9386
10010
|
"improvementId": {
|
|
9387
10011
|
"type": "string"
|
|
9388
10012
|
}
|
|
@@ -10050,6 +10674,10 @@
|
|
|
10050
10674
|
"schema": {
|
|
10051
10675
|
"type": "object",
|
|
10052
10676
|
"properties": {
|
|
10677
|
+
"projectId": {
|
|
10678
|
+
"type": "string",
|
|
10679
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
10680
|
+
},
|
|
10053
10681
|
"improvementId": {
|
|
10054
10682
|
"type": "string"
|
|
10055
10683
|
},
|
|
@@ -10176,6 +10804,10 @@
|
|
|
10176
10804
|
"schema": {
|
|
10177
10805
|
"type": "object",
|
|
10178
10806
|
"properties": {
|
|
10807
|
+
"projectId": {
|
|
10808
|
+
"type": "string",
|
|
10809
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
10810
|
+
},
|
|
10179
10811
|
"improvementId": {
|
|
10180
10812
|
"type": "string"
|
|
10181
10813
|
},
|
|
@@ -10792,8 +11424,13 @@
|
|
|
10792
11424
|
"schema": {
|
|
10793
11425
|
"type": "object",
|
|
10794
11426
|
"properties": {
|
|
11427
|
+
"projectId": {
|
|
11428
|
+
"type": "string",
|
|
11429
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
11430
|
+
},
|
|
10795
11431
|
"planId": {
|
|
10796
|
-
"type": "string"
|
|
11432
|
+
"type": "string",
|
|
11433
|
+
"description": "Accepts either the UUID or the friendly id (e.g. PLN-3); friendly ids are resolved within your organisation."
|
|
10797
11434
|
}
|
|
10798
11435
|
},
|
|
10799
11436
|
"required": [
|
|
@@ -11039,6 +11676,10 @@
|
|
|
11039
11676
|
"schema": {
|
|
11040
11677
|
"type": "object",
|
|
11041
11678
|
"properties": {
|
|
11679
|
+
"projectId": {
|
|
11680
|
+
"type": "string",
|
|
11681
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
11682
|
+
},
|
|
11042
11683
|
"planId": {
|
|
11043
11684
|
"type": "string"
|
|
11044
11685
|
},
|
|
@@ -11189,6 +11830,10 @@
|
|
|
11189
11830
|
"schema": {
|
|
11190
11831
|
"type": "object",
|
|
11191
11832
|
"properties": {
|
|
11833
|
+
"projectId": {
|
|
11834
|
+
"type": "string",
|
|
11835
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
11836
|
+
},
|
|
11192
11837
|
"planId": {
|
|
11193
11838
|
"type": "string"
|
|
11194
11839
|
}
|
|
@@ -11391,8 +12036,13 @@
|
|
|
11391
12036
|
"schema": {
|
|
11392
12037
|
"type": "object",
|
|
11393
12038
|
"properties": {
|
|
12039
|
+
"projectId": {
|
|
12040
|
+
"type": "string",
|
|
12041
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
12042
|
+
},
|
|
11394
12043
|
"phaseId": {
|
|
11395
|
-
"type": "string"
|
|
12044
|
+
"type": "string",
|
|
12045
|
+
"description": "Accepts either the UUID or the friendly id (e.g. PHA-7); friendly ids are resolved within your organisation."
|
|
11396
12046
|
}
|
|
11397
12047
|
},
|
|
11398
12048
|
"required": [
|
|
@@ -11638,6 +12288,10 @@
|
|
|
11638
12288
|
"schema": {
|
|
11639
12289
|
"type": "object",
|
|
11640
12290
|
"properties": {
|
|
12291
|
+
"projectId": {
|
|
12292
|
+
"type": "string",
|
|
12293
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
12294
|
+
},
|
|
11641
12295
|
"phaseId": {
|
|
11642
12296
|
"type": "string"
|
|
11643
12297
|
},
|
|
@@ -11788,6 +12442,10 @@
|
|
|
11788
12442
|
"schema": {
|
|
11789
12443
|
"type": "object",
|
|
11790
12444
|
"properties": {
|
|
12445
|
+
"projectId": {
|
|
12446
|
+
"type": "string",
|
|
12447
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
12448
|
+
},
|
|
11791
12449
|
"phaseId": {
|
|
11792
12450
|
"type": "string"
|
|
11793
12451
|
}
|
|
@@ -12006,6 +12664,10 @@
|
|
|
12006
12664
|
"schema": {
|
|
12007
12665
|
"type": "object",
|
|
12008
12666
|
"properties": {
|
|
12667
|
+
"projectId": {
|
|
12668
|
+
"type": "string",
|
|
12669
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
12670
|
+
},
|
|
12009
12671
|
"planId": {
|
|
12010
12672
|
"type": "string"
|
|
12011
12673
|
},
|
|
@@ -12333,7 +12995,7 @@
|
|
|
12333
12995
|
"/tools/createTask": {
|
|
12334
12996
|
"post": {
|
|
12335
12997
|
"summary": "createTask",
|
|
12336
|
-
"description": "Create a task in a plan. Requires planId and title.",
|
|
12998
|
+
"description": "Create a task in a plan. Requires planId and title. Accepts every field updateTask accepts, so a task can be created complete in ONE call — no create-then-update, and no window in which other actors read a half-written record.",
|
|
12337
12999
|
"operationId": "createTask",
|
|
12338
13000
|
"tags": [
|
|
12339
13001
|
"plans"
|
|
@@ -12360,7 +13022,7 @@
|
|
|
12360
13022
|
},
|
|
12361
13023
|
"type": {
|
|
12362
13024
|
"type": "string",
|
|
12363
|
-
"description": "Type. Default: task. Tasks created in plans are typed 'task' (friendly_id prefix TAS-). Override only if you want the row to appear as a non-task improvement (IMP- prefix)."
|
|
13025
|
+
"description": "Type. Default: task. Tasks created in plans are typed 'task' (friendly_id prefix TAS-). Override only if you want the row to appear as a non-task improvement (IMP- prefix). Valid values: feature, bug, tech_debt, architecture_gap, documentation_gap, risk, enhancement, task."
|
|
12364
13026
|
},
|
|
12365
13027
|
"status": {
|
|
12366
13028
|
"type": "string",
|
|
@@ -12370,6 +13032,36 @@
|
|
|
12370
13032
|
"type": "string",
|
|
12371
13033
|
"description": "Priority. Default: medium."
|
|
12372
13034
|
},
|
|
13035
|
+
"urgency": {
|
|
13036
|
+
"type": "string",
|
|
13037
|
+
"description": "e.g. this_week, this_month, this_quarter."
|
|
13038
|
+
},
|
|
13039
|
+
"source": {
|
|
13040
|
+
"type": "string",
|
|
13041
|
+
"description": "Where this task came from (free text, e.g. 'meeting', 'compliance-scan'). Stored for provenance and shown in the improvement/task record."
|
|
13042
|
+
},
|
|
13043
|
+
"source_channel": {
|
|
13044
|
+
"type": "string"
|
|
13045
|
+
},
|
|
13046
|
+
"category_id": {
|
|
13047
|
+
"type": "string",
|
|
13048
|
+
"description": "Category ID."
|
|
13049
|
+
},
|
|
13050
|
+
"problem_statement": {
|
|
13051
|
+
"type": "string"
|
|
13052
|
+
},
|
|
13053
|
+
"desired_outcome": {
|
|
13054
|
+
"type": "string"
|
|
13055
|
+
},
|
|
13056
|
+
"business_impact": {
|
|
13057
|
+
"type": "string"
|
|
13058
|
+
},
|
|
13059
|
+
"user_impact": {
|
|
13060
|
+
"type": "string"
|
|
13061
|
+
},
|
|
13062
|
+
"why_now": {
|
|
13063
|
+
"type": "string"
|
|
13064
|
+
},
|
|
12373
13065
|
"acceptance_criteria": {
|
|
12374
13066
|
"type": "array",
|
|
12375
13067
|
"description": "Acceptance criteria — ordered list of pass/fail statements that define \"done\" for this item. Each row is `{ id, text }` with server-stamped `updated_at / updated_by / updated_by_credential_name`. REPLACES the whole array on update. Echo back existing `id`s on rows you keep so attribution stamps survive. Bare strings are accepted for convenience (e.g. `[\"row 1\", \"row 2\"]`) and auto-converted to `{ id, text }`.",
|
|
@@ -12382,6 +13074,18 @@
|
|
|
12382
13074
|
},
|
|
12383
13075
|
"text": {
|
|
12384
13076
|
"type": "string"
|
|
13077
|
+
},
|
|
13078
|
+
"updated_at": {
|
|
13079
|
+
"type": "string",
|
|
13080
|
+
"description": "Server-stamped. Echo back unchanged; ignored on new rows."
|
|
13081
|
+
},
|
|
13082
|
+
"updated_by": {
|
|
13083
|
+
"type": "string",
|
|
13084
|
+
"description": "Server-stamped user id. Echo back unchanged."
|
|
13085
|
+
},
|
|
13086
|
+
"updated_by_credential_name": {
|
|
13087
|
+
"type": "string",
|
|
13088
|
+
"description": "Server-stamped credential label. Echo back unchanged."
|
|
12385
13089
|
}
|
|
12386
13090
|
},
|
|
12387
13091
|
"required": [
|
|
@@ -12409,6 +13113,30 @@
|
|
|
12409
13113
|
"completed": {
|
|
12410
13114
|
"type": "boolean",
|
|
12411
13115
|
"description": "true = ticked, false/omitted = not done. Server stamps timestamp + actor."
|
|
13116
|
+
},
|
|
13117
|
+
"completed_at": {
|
|
13118
|
+
"type": "string",
|
|
13119
|
+
"description": "Server-stamped ISO timestamp. Prefer `completed`; an explicit value here wins if both are sent."
|
|
13120
|
+
},
|
|
13121
|
+
"completed_by": {
|
|
13122
|
+
"type": "string",
|
|
13123
|
+
"description": "Server-stamped user id. Echo back unchanged."
|
|
13124
|
+
},
|
|
13125
|
+
"completed_by_credential_name": {
|
|
13126
|
+
"type": "string",
|
|
13127
|
+
"description": "Server-stamped credential label. Echo back unchanged."
|
|
13128
|
+
},
|
|
13129
|
+
"updated_at": {
|
|
13130
|
+
"type": "string",
|
|
13131
|
+
"description": "Server-stamped. Echo back unchanged; ignored on new rows."
|
|
13132
|
+
},
|
|
13133
|
+
"updated_by": {
|
|
13134
|
+
"type": "string",
|
|
13135
|
+
"description": "Server-stamped user id. Echo back unchanged."
|
|
13136
|
+
},
|
|
13137
|
+
"updated_by_credential_name": {
|
|
13138
|
+
"type": "string",
|
|
13139
|
+
"description": "Server-stamped credential label. Echo back unchanged."
|
|
12412
13140
|
}
|
|
12413
13141
|
},
|
|
12414
13142
|
"required": [
|
|
@@ -12416,6 +13144,74 @@
|
|
|
12416
13144
|
]
|
|
12417
13145
|
}
|
|
12418
13146
|
},
|
|
13147
|
+
"constraints": {
|
|
13148
|
+
"type": "array",
|
|
13149
|
+
"items": {
|
|
13150
|
+
"type": "string"
|
|
13151
|
+
}
|
|
13152
|
+
},
|
|
13153
|
+
"non_goals": {
|
|
13154
|
+
"type": "array",
|
|
13155
|
+
"items": {
|
|
13156
|
+
"type": "string"
|
|
13157
|
+
}
|
|
13158
|
+
},
|
|
13159
|
+
"impacted_documents": {
|
|
13160
|
+
"type": "array",
|
|
13161
|
+
"items": {
|
|
13162
|
+
"type": "object"
|
|
13163
|
+
},
|
|
13164
|
+
"description": "Array of {id, title}."
|
|
13165
|
+
},
|
|
13166
|
+
"linked_document_ids": {
|
|
13167
|
+
"type": "array",
|
|
13168
|
+
"items": {
|
|
13169
|
+
"type": "string"
|
|
13170
|
+
},
|
|
13171
|
+
"description": "Document IDs to link. Titles resolved automatically."
|
|
13172
|
+
},
|
|
13173
|
+
"impacted_diagrams": {
|
|
13174
|
+
"type": "array",
|
|
13175
|
+
"items": {
|
|
13176
|
+
"type": "object"
|
|
13177
|
+
},
|
|
13178
|
+
"description": "Array of {id, name}."
|
|
13179
|
+
},
|
|
13180
|
+
"impacted_components": {
|
|
13181
|
+
"type": "array",
|
|
13182
|
+
"items": {
|
|
13183
|
+
"type": "string"
|
|
13184
|
+
}
|
|
13185
|
+
},
|
|
13186
|
+
"impacted_repositories": {
|
|
13187
|
+
"type": "array",
|
|
13188
|
+
"items": {
|
|
13189
|
+
"type": "string"
|
|
13190
|
+
}
|
|
13191
|
+
},
|
|
13192
|
+
"agent_ready": {
|
|
13193
|
+
"type": "boolean"
|
|
13194
|
+
},
|
|
13195
|
+
"agent_missing_info": {
|
|
13196
|
+
"type": "array",
|
|
13197
|
+
"items": {
|
|
13198
|
+
"type": "string"
|
|
13199
|
+
}
|
|
13200
|
+
},
|
|
13201
|
+
"agent_recommended_action": {
|
|
13202
|
+
"type": "string"
|
|
13203
|
+
},
|
|
13204
|
+
"agent_complexity": {
|
|
13205
|
+
"type": "string",
|
|
13206
|
+
"description": "low, medium, high, very_high."
|
|
13207
|
+
},
|
|
13208
|
+
"agent_confidence": {
|
|
13209
|
+
"type": "number",
|
|
13210
|
+
"description": "0.00 to 1.00."
|
|
13211
|
+
},
|
|
13212
|
+
"agent_brief": {
|
|
13213
|
+
"type": "string"
|
|
13214
|
+
},
|
|
12419
13215
|
"owner_id": {
|
|
12420
13216
|
"type": "string",
|
|
12421
13217
|
"description": "User UUID to assign as owner. MUTUALLY EXCLUSIVE with owner_team_id. Use listAssignablePrincipals(projectId, kind='user') to look up valid UUIDs."
|
|
@@ -12445,6 +13241,14 @@
|
|
|
12445
13241
|
"percent_complete": {
|
|
12446
13242
|
"type": "number",
|
|
12447
13243
|
"description": "Progress percentage (0-100). Null means not tracked."
|
|
13244
|
+
},
|
|
13245
|
+
"relationships": {
|
|
13246
|
+
"type": "object",
|
|
13247
|
+
"description": "Free-form JSON for logical links: blocks, blocked_by, duplicates, supersedes, relates_to (arrays of item IDs)."
|
|
13248
|
+
},
|
|
13249
|
+
"metadata": {
|
|
13250
|
+
"type": "object",
|
|
13251
|
+
"description": "Free-form JSON stored alongside the task. On updateTask this MERGES rather than replaces."
|
|
12448
13252
|
}
|
|
12449
13253
|
},
|
|
12450
13254
|
"required": [
|
|
@@ -12686,8 +13490,13 @@
|
|
|
12686
13490
|
"schema": {
|
|
12687
13491
|
"type": "object",
|
|
12688
13492
|
"properties": {
|
|
13493
|
+
"projectId": {
|
|
13494
|
+
"type": "string",
|
|
13495
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
13496
|
+
},
|
|
12689
13497
|
"taskId": {
|
|
12690
|
-
"type": "string"
|
|
13498
|
+
"type": "string",
|
|
13499
|
+
"description": "Accepts either the UUID or the friendly id (e.g. TAS-176); friendly ids are resolved within your organisation."
|
|
12691
13500
|
}
|
|
12692
13501
|
},
|
|
12693
13502
|
"required": [
|
|
@@ -12775,7 +13584,7 @@
|
|
|
12775
13584
|
"/tools/updateTask": {
|
|
12776
13585
|
"post": {
|
|
12777
13586
|
"summary": "updateTask",
|
|
12778
|
-
"description": "Update a task. Tasks share a row with improvements (`improvement_items` with `is_task=true`), so this is a thin alias over updateImprovement — every field on updateImprovement is supported, including `checklist`, `acceptance_criteria`,
|
|
13587
|
+
"description": "Update a task. Tasks share a row with improvements (`improvement_items` with `is_task=true`), so this is a thin alias over updateImprovement — every field on updateImprovement is supported, including `checklist`, `acceptance_criteria`, dates, owner, percent_complete, etc. Requires versionTimestamp from getTask for optimistic locking. Statuses are captured / in_progress / blocked / done / rejected / deferred, and FOUR of those are CLOSED: blocked, done, rejected, deferred. Entering one needs its comment (blocked_comment / rejection_comment / completion_comment); leaving one for an open status needs reopened_comment — including blocked -> in_progress, which surprises people because `blocked` does not sound terminal. `metadata` MERGES into what is stored (null on a key deletes it); pass metadata_replace:true to overwrite the object wholesale. To edit checklist items: call getTask, modify the `checklist` array (preserving each row's `id` to keep its attribution stamps), and pass the full array back here — array order is the sort order. Assignment: pass `owner_id=<uuid>` to assign to a user, `owner_team_id=<uuid>` to assign to a team (mutually exclusive — the DB enforces with a CHECK constraint). To unassign, pass `owner_id=null` AND `owner_team_id=null`. To switch owner kind, send the new value AND null the old one in the SAME call.",
|
|
12779
13588
|
"operationId": "updateTask",
|
|
12780
13589
|
"tags": [
|
|
12781
13590
|
"plans"
|
|
@@ -12787,6 +13596,10 @@
|
|
|
12787
13596
|
"schema": {
|
|
12788
13597
|
"type": "object",
|
|
12789
13598
|
"properties": {
|
|
13599
|
+
"projectId": {
|
|
13600
|
+
"type": "string",
|
|
13601
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
13602
|
+
},
|
|
12790
13603
|
"taskId": {
|
|
12791
13604
|
"type": "string"
|
|
12792
13605
|
},
|
|
@@ -12875,6 +13688,18 @@
|
|
|
12875
13688
|
},
|
|
12876
13689
|
"text": {
|
|
12877
13690
|
"type": "string"
|
|
13691
|
+
},
|
|
13692
|
+
"updated_at": {
|
|
13693
|
+
"type": "string",
|
|
13694
|
+
"description": "Server-stamped. Echo back unchanged; ignored on new rows."
|
|
13695
|
+
},
|
|
13696
|
+
"updated_by": {
|
|
13697
|
+
"type": "string",
|
|
13698
|
+
"description": "Server-stamped user id. Echo back unchanged."
|
|
13699
|
+
},
|
|
13700
|
+
"updated_by_credential_name": {
|
|
13701
|
+
"type": "string",
|
|
13702
|
+
"description": "Server-stamped credential label. Echo back unchanged."
|
|
12878
13703
|
}
|
|
12879
13704
|
},
|
|
12880
13705
|
"required": [
|
|
@@ -12902,6 +13727,30 @@
|
|
|
12902
13727
|
"completed": {
|
|
12903
13728
|
"type": "boolean",
|
|
12904
13729
|
"description": "true = ticked, false/omitted = not done. Server stamps timestamp + actor."
|
|
13730
|
+
},
|
|
13731
|
+
"completed_at": {
|
|
13732
|
+
"type": "string",
|
|
13733
|
+
"description": "Server-stamped ISO timestamp. Prefer `completed`; an explicit value here wins if both are sent."
|
|
13734
|
+
},
|
|
13735
|
+
"completed_by": {
|
|
13736
|
+
"type": "string",
|
|
13737
|
+
"description": "Server-stamped user id. Echo back unchanged."
|
|
13738
|
+
},
|
|
13739
|
+
"completed_by_credential_name": {
|
|
13740
|
+
"type": "string",
|
|
13741
|
+
"description": "Server-stamped credential label. Echo back unchanged."
|
|
13742
|
+
},
|
|
13743
|
+
"updated_at": {
|
|
13744
|
+
"type": "string",
|
|
13745
|
+
"description": "Server-stamped. Echo back unchanged; ignored on new rows."
|
|
13746
|
+
},
|
|
13747
|
+
"updated_by": {
|
|
13748
|
+
"type": "string",
|
|
13749
|
+
"description": "Server-stamped user id. Echo back unchanged."
|
|
13750
|
+
},
|
|
13751
|
+
"updated_by_credential_name": {
|
|
13752
|
+
"type": "string",
|
|
13753
|
+
"description": "Server-stamped credential label. Echo back unchanged."
|
|
12905
13754
|
}
|
|
12906
13755
|
},
|
|
12907
13756
|
"required": [
|
|
@@ -12999,14 +13848,19 @@
|
|
|
12999
13848
|
},
|
|
13000
13849
|
"reopened_comment": {
|
|
13001
13850
|
"type": "string",
|
|
13002
|
-
"description": "Required when
|
|
13851
|
+
"description": "Required when moving OUT of a closed status. The closed set is blocked, done, rejected and deferred — note that `blocked` counts as closed, so blocked -> in_progress needs this comment."
|
|
13003
13852
|
},
|
|
13004
13853
|
"relationships": {
|
|
13005
13854
|
"type": "object",
|
|
13006
|
-
"description": "Free-form JSON for logical links: blocks, blocked_by, duplicates, supersedes, relates_to (arrays of item IDs)."
|
|
13855
|
+
"description": "Free-form JSON for logical links: blocks, blocked_by, duplicates, supersedes, relates_to (arrays of item IDs). REPLACES the stored object wholesale — read it first and send the complete set."
|
|
13007
13856
|
},
|
|
13008
13857
|
"metadata": {
|
|
13009
|
-
"type": "object"
|
|
13858
|
+
"type": "object",
|
|
13859
|
+
"description": "Free-form JSON. MERGES into the stored object key by key: keys you don't send are left alone, and sending a key with value null deletes it. Send metadata_replace:true to overwrite the whole object instead. (Merging is the default so a partial write can never destroy a sibling key written by another actor.)"
|
|
13860
|
+
},
|
|
13861
|
+
"metadata_replace": {
|
|
13862
|
+
"type": "boolean",
|
|
13863
|
+
"description": "Opt out of the metadata merge: true means the object you send REPLACES everything stored, deleting any key you omit. Default false."
|
|
13010
13864
|
},
|
|
13011
13865
|
"plan_id": {
|
|
13012
13866
|
"type": "string",
|
|
@@ -13115,8 +13969,13 @@
|
|
|
13115
13969
|
"schema": {
|
|
13116
13970
|
"type": "object",
|
|
13117
13971
|
"properties": {
|
|
13972
|
+
"projectId": {
|
|
13973
|
+
"type": "string",
|
|
13974
|
+
"description": "Optional. Narrows a friendly-id lookup to one project. Only needed when a friendly id is ambiguous — TAS-/IMP-/PLN- ids are numbered per PROJECT, so the same id can exist in several. Ignored when the id is a UUID."
|
|
13975
|
+
},
|
|
13118
13976
|
"planId": {
|
|
13119
|
-
"type": "string"
|
|
13977
|
+
"type": "string",
|
|
13978
|
+
"description": "Accepts either the UUID or the friendly id (e.g. PLN-3); friendly ids are resolved within your organisation."
|
|
13120
13979
|
}
|
|
13121
13980
|
},
|
|
13122
13981
|
"required": [
|
|
@@ -13660,7 +14519,7 @@
|
|
|
13660
14519
|
"/tools/deleteTaskDependency": {
|
|
13661
14520
|
"post": {
|
|
13662
14521
|
"summary": "deleteTaskDependency",
|
|
13663
|
-
"description": "Remove a task-dependency edge. Neither item's dates are changed.",
|
|
14522
|
+
"description": "Remove a task-dependency edge. Neither item's dates are changed. Needs the same 'write' plan permission as createTaskDependency, so an actor that can draw an edge can also undo it — the edge is fully recreatable from (predecessor, successor, type, lag).",
|
|
13664
14523
|
"operationId": "deleteTaskDependency",
|
|
13665
14524
|
"tags": [
|
|
13666
14525
|
"plans"
|
|
@@ -14217,10 +15076,12 @@
|
|
|
14217
15076
|
"description": "Retrieval strategy. See tool description for when to use each — strongly prefer 'global' for thematic/overview questions."
|
|
14218
15077
|
},
|
|
14219
15078
|
"projectId": {
|
|
14220
|
-
"type": "string"
|
|
15079
|
+
"type": "string",
|
|
15080
|
+
"description": "STRONGLY RECOMMENDED — in practice required. The KG is scoped per project/workspace and there is usually no organisation-wide default, so a call with no projectId and no workspaceId typically matches no scope rule and returns nothing useful. Use listProjects to find the id."
|
|
14221
15081
|
},
|
|
14222
15082
|
"workspaceId": {
|
|
14223
|
-
"type": "string"
|
|
15083
|
+
"type": "string",
|
|
15084
|
+
"description": "Alternative to projectId — searches the whole workspace subtree. Give one of the two."
|
|
14224
15085
|
},
|
|
14225
15086
|
"srcEntityId": {
|
|
14226
15087
|
"type": "string",
|
|
@@ -14444,6 +15305,10 @@
|
|
|
14444
15305
|
},
|
|
14445
15306
|
"name": {
|
|
14446
15307
|
"type": "string"
|
|
15308
|
+
},
|
|
15309
|
+
"projectId": {
|
|
15310
|
+
"type": "string",
|
|
15311
|
+
"description": "Scope the lookup to one project. Recommended when resolving by `name`, since the same entity name can exist in several projects."
|
|
14447
15312
|
}
|
|
14448
15313
|
}
|
|
14449
15314
|
}
|