@stablebaseline/sdk 0.5.1 → 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 +262 -29
- package/dist/index.d.ts +262 -29
- package/openapi.json +542 -48
- package/package.json +1 -1
- package/src/types.generated.ts +262 -29
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
|
}
|
|
@@ -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 (standard Markdown plus SB extensions — call getCdmdLanguageGuide if unfamiliar). The body goes in `cdmd` (`content` is accepted as an alias). Do not include DIAGRAM/IMAGE markers — insert them after with dedicated tools. Returns the new document's id and versionTimestamp (the optimistic-lock token for subsequent edits). Supports @-mentioning people: embed `<!-- REFERENCE: {\"type\":\"user\",\"id\":\"<user_uuid>\",\"label\":\"Name\"} -->` to notify a teammate. Use listAssignablePrincipals to look up the user_id from a name; mentions of users outside the project are silently dropped.",
|
|
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"
|
|
@@ -2849,6 +2876,10 @@
|
|
|
2849
2876
|
"schema": {
|
|
2850
2877
|
"type": "object",
|
|
2851
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
|
+
},
|
|
2852
2883
|
"documentId": {
|
|
2853
2884
|
"type": "string"
|
|
2854
2885
|
},
|
|
@@ -2857,17 +2888,24 @@
|
|
|
2857
2888
|
"description": "New title."
|
|
2858
2889
|
},
|
|
2859
2890
|
"folderId": {
|
|
2860
|
-
"type":
|
|
2861
|
-
|
|
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."
|
|
2862
2896
|
},
|
|
2863
2897
|
"position": {
|
|
2864
2898
|
"type": "number",
|
|
2865
|
-
"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."
|
|
2866
2900
|
},
|
|
2867
2901
|
"versionTimestamp": {
|
|
2868
2902
|
"type": "number",
|
|
2869
2903
|
"description": "Optimistic-lock token from getDocument() or any mutating tool's response. Required unless dryRun:true. (Alias accepted: documentVersionTimestamp.)"
|
|
2870
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."
|
|
2908
|
+
},
|
|
2871
2909
|
"dryRun": {
|
|
2872
2910
|
"type": "boolean",
|
|
2873
2911
|
"description": "If true, apply the patches and RETURN the resulting document text without saving — no version bump, no lock required. Use to preview/verify a patch before committing. Default false."
|
|
@@ -3031,6 +3069,10 @@
|
|
|
3031
3069
|
"schema": {
|
|
3032
3070
|
"type": "object",
|
|
3033
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
|
+
},
|
|
3034
3076
|
"documentId": {
|
|
3035
3077
|
"type": "string"
|
|
3036
3078
|
},
|
|
@@ -3263,6 +3305,10 @@
|
|
|
3263
3305
|
"schema": {
|
|
3264
3306
|
"type": "object",
|
|
3265
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
|
+
},
|
|
3266
3312
|
"documentId": {
|
|
3267
3313
|
"type": "string"
|
|
3268
3314
|
},
|
|
@@ -3705,6 +3751,10 @@
|
|
|
3705
3751
|
"properties": {
|
|
3706
3752
|
"documentId": {
|
|
3707
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."
|
|
3708
3758
|
}
|
|
3709
3759
|
},
|
|
3710
3760
|
"required": [
|
|
@@ -4090,6 +4140,10 @@
|
|
|
4090
4140
|
"type": "string",
|
|
4091
4141
|
"description": "Optional URL of a reference image the component should match; the critic compares the render to it."
|
|
4092
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
|
+
},
|
|
4093
4147
|
"force": {
|
|
4094
4148
|
"type": "boolean",
|
|
4095
4149
|
"description": "Redesign even if a component with this key already exists (default false = reuse)."
|
|
@@ -4305,7 +4359,7 @@
|
|
|
4305
4359
|
"/tools/designDeckInWhiteboard": {
|
|
4306
4360
|
"post": {
|
|
4307
4361
|
"summary": "designDeckInWhiteboard",
|
|
4308
|
-
"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.",
|
|
4309
4363
|
"operationId": "designDeckInWhiteboard",
|
|
4310
4364
|
"tags": [
|
|
4311
4365
|
"whiteboards"
|
|
@@ -4323,7 +4377,7 @@
|
|
|
4323
4377
|
},
|
|
4324
4378
|
"message": {
|
|
4325
4379
|
"type": "string",
|
|
4326
|
-
"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."
|
|
4327
4381
|
},
|
|
4328
4382
|
"sessionId": {
|
|
4329
4383
|
"type": "string",
|
|
@@ -4353,7 +4407,19 @@
|
|
|
4353
4407
|
},
|
|
4354
4408
|
"slideCount": {
|
|
4355
4409
|
"type": "number",
|
|
4356
|
-
"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."
|
|
4357
4423
|
},
|
|
4358
4424
|
"attachments": {
|
|
4359
4425
|
"type": "array",
|
|
@@ -4377,6 +4443,10 @@
|
|
|
4377
4443
|
"name": {
|
|
4378
4444
|
"type": "string",
|
|
4379
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."
|
|
4380
4450
|
}
|
|
4381
4451
|
}
|
|
4382
4452
|
}
|
|
@@ -4530,6 +4600,10 @@
|
|
|
4530
4600
|
"name": {
|
|
4531
4601
|
"type": "string",
|
|
4532
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."
|
|
4533
4607
|
}
|
|
4534
4608
|
}
|
|
4535
4609
|
}
|
|
@@ -4625,7 +4699,7 @@
|
|
|
4625
4699
|
"/tools/getDeckReplyInWhiteboard": {
|
|
4626
4700
|
"post": {
|
|
4627
4701
|
"summary": "getDeckReplyInWhiteboard",
|
|
4628
|
-
"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.",
|
|
4629
4703
|
"operationId": "getDeckReplyInWhiteboard",
|
|
4630
4704
|
"tags": [
|
|
4631
4705
|
"whiteboards"
|
|
@@ -4894,6 +4968,15 @@
|
|
|
4894
4968
|
"id": {
|
|
4895
4969
|
"type": "string",
|
|
4896
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."
|
|
4897
4980
|
}
|
|
4898
4981
|
},
|
|
4899
4982
|
"required": [
|
|
@@ -5424,8 +5507,13 @@
|
|
|
5424
5507
|
"schema": {
|
|
5425
5508
|
"type": "object",
|
|
5426
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
|
+
},
|
|
5427
5514
|
"documentId": {
|
|
5428
|
-
"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."
|
|
5429
5517
|
},
|
|
5430
5518
|
"includeElements": {
|
|
5431
5519
|
"type": "boolean",
|
|
@@ -5529,6 +5617,10 @@
|
|
|
5529
5617
|
"schema": {
|
|
5530
5618
|
"type": "object",
|
|
5531
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
|
+
},
|
|
5532
5624
|
"documentId": {
|
|
5533
5625
|
"type": "string"
|
|
5534
5626
|
},
|
|
@@ -5669,6 +5761,10 @@
|
|
|
5669
5761
|
"schema": {
|
|
5670
5762
|
"type": "object",
|
|
5671
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
|
+
},
|
|
5672
5768
|
"documentId": {
|
|
5673
5769
|
"type": "string"
|
|
5674
5770
|
},
|
|
@@ -6167,6 +6263,15 @@
|
|
|
6167
6263
|
"locked": {
|
|
6168
6264
|
"type": "boolean",
|
|
6169
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."
|
|
6170
6275
|
}
|
|
6171
6276
|
},
|
|
6172
6277
|
"required": [
|
|
@@ -6561,6 +6666,10 @@
|
|
|
6561
6666
|
"schema": {
|
|
6562
6667
|
"type": "object",
|
|
6563
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
|
+
},
|
|
6564
6673
|
"documentId": {
|
|
6565
6674
|
"type": "string",
|
|
6566
6675
|
"description": "The whiteboard's documentId."
|
|
@@ -6814,9 +6923,13 @@
|
|
|
6814
6923
|
"schema": {
|
|
6815
6924
|
"type": "object",
|
|
6816
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
|
+
},
|
|
6817
6930
|
"documentId": {
|
|
6818
6931
|
"type": "string",
|
|
6819
|
-
"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."
|
|
6820
6933
|
},
|
|
6821
6934
|
"elementIds": {
|
|
6822
6935
|
"type": "array",
|
|
@@ -6966,6 +7079,10 @@
|
|
|
6966
7079
|
"properties": {
|
|
6967
7080
|
"documentId": {
|
|
6968
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."
|
|
6969
7086
|
}
|
|
6970
7087
|
},
|
|
6971
7088
|
"required": [
|
|
@@ -7416,7 +7533,7 @@
|
|
|
7416
7533
|
"/tools/reorderDocuments": {
|
|
7417
7534
|
"post": {
|
|
7418
7535
|
"summary": "reorderDocuments",
|
|
7419
|
-
"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).",
|
|
7420
7537
|
"operationId": "reorderDocuments",
|
|
7421
7538
|
"tags": [
|
|
7422
7539
|
"documents"
|
|
@@ -7430,7 +7547,7 @@
|
|
|
7430
7547
|
"properties": {
|
|
7431
7548
|
"items": {
|
|
7432
7549
|
"type": "array",
|
|
7433
|
-
"description": "
|
|
7550
|
+
"description": "Documents to file. All must belong to the same project (a batch spanning projects is rejected).",
|
|
7434
7551
|
"items": {
|
|
7435
7552
|
"type": "object",
|
|
7436
7553
|
"properties": {
|
|
@@ -7438,7 +7555,15 @@
|
|
|
7438
7555
|
"type": "string"
|
|
7439
7556
|
},
|
|
7440
7557
|
"position": {
|
|
7441
|
-
"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."
|
|
7442
7567
|
}
|
|
7443
7568
|
},
|
|
7444
7569
|
"required": [
|
|
@@ -7546,8 +7671,13 @@
|
|
|
7546
7671
|
"schema": {
|
|
7547
7672
|
"type": "object",
|
|
7548
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
|
+
},
|
|
7549
7678
|
"documentId": {
|
|
7550
|
-
"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."
|
|
7551
7681
|
},
|
|
7552
7682
|
"versionNumber": {
|
|
7553
7683
|
"type": "number",
|
|
@@ -7784,6 +7914,10 @@
|
|
|
7784
7914
|
"schema": {
|
|
7785
7915
|
"type": "object",
|
|
7786
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
|
+
},
|
|
7787
7921
|
"documentId": {
|
|
7788
7922
|
"type": "string"
|
|
7789
7923
|
},
|
|
@@ -7899,6 +8033,10 @@
|
|
|
7899
8033
|
"schema": {
|
|
7900
8034
|
"type": "object",
|
|
7901
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
|
+
},
|
|
7902
8040
|
"documentId": {
|
|
7903
8041
|
"type": "string"
|
|
7904
8042
|
},
|
|
@@ -8295,6 +8433,10 @@
|
|
|
8295
8433
|
"schema": {
|
|
8296
8434
|
"type": "object",
|
|
8297
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
|
+
},
|
|
8298
8440
|
"documentId": {
|
|
8299
8441
|
"type": "string"
|
|
8300
8442
|
},
|
|
@@ -8405,6 +8547,10 @@
|
|
|
8405
8547
|
"schema": {
|
|
8406
8548
|
"type": "object",
|
|
8407
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
|
+
},
|
|
8408
8554
|
"documentId": {
|
|
8409
8555
|
"type": "string"
|
|
8410
8556
|
},
|
|
@@ -9023,8 +9169,13 @@
|
|
|
9023
9169
|
"schema": {
|
|
9024
9170
|
"type": "object",
|
|
9025
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
|
+
},
|
|
9026
9176
|
"improvementId": {
|
|
9027
|
-
"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."
|
|
9028
9179
|
}
|
|
9029
9180
|
},
|
|
9030
9181
|
"required": [
|
|
@@ -9112,7 +9263,7 @@
|
|
|
9112
9263
|
"/tools/createImprovement": {
|
|
9113
9264
|
"post": {
|
|
9114
9265
|
"summary": "createImprovement",
|
|
9115
|
-
"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.",
|
|
9116
9267
|
"operationId": "createImprovement",
|
|
9117
9268
|
"tags": [
|
|
9118
9269
|
"improvements"
|
|
@@ -9132,7 +9283,7 @@
|
|
|
9132
9283
|
},
|
|
9133
9284
|
"type": {
|
|
9134
9285
|
"type": "string",
|
|
9135
|
-
"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)."
|
|
9136
9287
|
},
|
|
9137
9288
|
"priority": {
|
|
9138
9289
|
"type": "string",
|
|
@@ -9181,6 +9332,18 @@
|
|
|
9181
9332
|
},
|
|
9182
9333
|
"text": {
|
|
9183
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."
|
|
9343
|
+
},
|
|
9344
|
+
"updated_by_credential_name": {
|
|
9345
|
+
"type": "string",
|
|
9346
|
+
"description": "Server-stamped credential label. Echo back unchanged."
|
|
9184
9347
|
}
|
|
9185
9348
|
},
|
|
9186
9349
|
"required": [
|
|
@@ -9208,6 +9371,30 @@
|
|
|
9208
9371
|
"completed": {
|
|
9209
9372
|
"type": "boolean",
|
|
9210
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."
|
|
9211
9398
|
}
|
|
9212
9399
|
},
|
|
9213
9400
|
"required": [
|
|
@@ -9319,6 +9506,23 @@
|
|
|
9319
9506
|
"percent_complete": {
|
|
9320
9507
|
"type": "number",
|
|
9321
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."
|
|
9322
9526
|
}
|
|
9323
9527
|
},
|
|
9324
9528
|
"required": [
|
|
@@ -9407,7 +9611,7 @@
|
|
|
9407
9611
|
"/tools/updateImprovement": {
|
|
9408
9612
|
"post": {
|
|
9409
9613
|
"summary": "updateImprovement",
|
|
9410
|
-
"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.",
|
|
9411
9615
|
"operationId": "updateImprovement",
|
|
9412
9616
|
"tags": [
|
|
9413
9617
|
"improvements"
|
|
@@ -9419,6 +9623,10 @@
|
|
|
9419
9623
|
"schema": {
|
|
9420
9624
|
"type": "object",
|
|
9421
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
|
+
},
|
|
9422
9630
|
"improvementId": {
|
|
9423
9631
|
"type": "string"
|
|
9424
9632
|
},
|
|
@@ -9500,6 +9708,18 @@
|
|
|
9500
9708
|
},
|
|
9501
9709
|
"text": {
|
|
9502
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."
|
|
9503
9723
|
}
|
|
9504
9724
|
},
|
|
9505
9725
|
"required": [
|
|
@@ -9527,6 +9747,30 @@
|
|
|
9527
9747
|
"completed": {
|
|
9528
9748
|
"type": "boolean",
|
|
9529
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."
|
|
9530
9774
|
}
|
|
9531
9775
|
},
|
|
9532
9776
|
"required": [
|
|
@@ -9624,14 +9868,19 @@
|
|
|
9624
9868
|
},
|
|
9625
9869
|
"reopened_comment": {
|
|
9626
9870
|
"type": "string",
|
|
9627
|
-
"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."
|
|
9628
9872
|
},
|
|
9629
9873
|
"relationships": {
|
|
9630
9874
|
"type": "object",
|
|
9631
|
-
"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."
|
|
9632
9876
|
},
|
|
9633
9877
|
"metadata": {
|
|
9634
|
-
"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."
|
|
9635
9884
|
},
|
|
9636
9885
|
"plan_id": {
|
|
9637
9886
|
"type": "string",
|
|
@@ -9754,6 +10003,10 @@
|
|
|
9754
10003
|
"schema": {
|
|
9755
10004
|
"type": "object",
|
|
9756
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
|
+
},
|
|
9757
10010
|
"improvementId": {
|
|
9758
10011
|
"type": "string"
|
|
9759
10012
|
}
|
|
@@ -10421,6 +10674,10 @@
|
|
|
10421
10674
|
"schema": {
|
|
10422
10675
|
"type": "object",
|
|
10423
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
|
+
},
|
|
10424
10681
|
"improvementId": {
|
|
10425
10682
|
"type": "string"
|
|
10426
10683
|
},
|
|
@@ -10547,6 +10804,10 @@
|
|
|
10547
10804
|
"schema": {
|
|
10548
10805
|
"type": "object",
|
|
10549
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
|
+
},
|
|
10550
10811
|
"improvementId": {
|
|
10551
10812
|
"type": "string"
|
|
10552
10813
|
},
|
|
@@ -11163,8 +11424,13 @@
|
|
|
11163
11424
|
"schema": {
|
|
11164
11425
|
"type": "object",
|
|
11165
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
|
+
},
|
|
11166
11431
|
"planId": {
|
|
11167
|
-
"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."
|
|
11168
11434
|
}
|
|
11169
11435
|
},
|
|
11170
11436
|
"required": [
|
|
@@ -11410,6 +11676,10 @@
|
|
|
11410
11676
|
"schema": {
|
|
11411
11677
|
"type": "object",
|
|
11412
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
|
+
},
|
|
11413
11683
|
"planId": {
|
|
11414
11684
|
"type": "string"
|
|
11415
11685
|
},
|
|
@@ -11560,6 +11830,10 @@
|
|
|
11560
11830
|
"schema": {
|
|
11561
11831
|
"type": "object",
|
|
11562
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
|
+
},
|
|
11563
11837
|
"planId": {
|
|
11564
11838
|
"type": "string"
|
|
11565
11839
|
}
|
|
@@ -11762,8 +12036,13 @@
|
|
|
11762
12036
|
"schema": {
|
|
11763
12037
|
"type": "object",
|
|
11764
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
|
+
},
|
|
11765
12043
|
"phaseId": {
|
|
11766
|
-
"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."
|
|
11767
12046
|
}
|
|
11768
12047
|
},
|
|
11769
12048
|
"required": [
|
|
@@ -12009,6 +12288,10 @@
|
|
|
12009
12288
|
"schema": {
|
|
12010
12289
|
"type": "object",
|
|
12011
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
|
+
},
|
|
12012
12295
|
"phaseId": {
|
|
12013
12296
|
"type": "string"
|
|
12014
12297
|
},
|
|
@@ -12159,6 +12442,10 @@
|
|
|
12159
12442
|
"schema": {
|
|
12160
12443
|
"type": "object",
|
|
12161
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
|
+
},
|
|
12162
12449
|
"phaseId": {
|
|
12163
12450
|
"type": "string"
|
|
12164
12451
|
}
|
|
@@ -12377,6 +12664,10 @@
|
|
|
12377
12664
|
"schema": {
|
|
12378
12665
|
"type": "object",
|
|
12379
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
|
+
},
|
|
12380
12671
|
"planId": {
|
|
12381
12672
|
"type": "string"
|
|
12382
12673
|
},
|
|
@@ -12704,7 +12995,7 @@
|
|
|
12704
12995
|
"/tools/createTask": {
|
|
12705
12996
|
"post": {
|
|
12706
12997
|
"summary": "createTask",
|
|
12707
|
-
"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.",
|
|
12708
12999
|
"operationId": "createTask",
|
|
12709
13000
|
"tags": [
|
|
12710
13001
|
"plans"
|
|
@@ -12731,7 +13022,7 @@
|
|
|
12731
13022
|
},
|
|
12732
13023
|
"type": {
|
|
12733
13024
|
"type": "string",
|
|
12734
|
-
"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."
|
|
12735
13026
|
},
|
|
12736
13027
|
"status": {
|
|
12737
13028
|
"type": "string",
|
|
@@ -12741,6 +13032,36 @@
|
|
|
12741
13032
|
"type": "string",
|
|
12742
13033
|
"description": "Priority. Default: medium."
|
|
12743
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
|
+
},
|
|
12744
13065
|
"acceptance_criteria": {
|
|
12745
13066
|
"type": "array",
|
|
12746
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 }`.",
|
|
@@ -12753,6 +13074,18 @@
|
|
|
12753
13074
|
},
|
|
12754
13075
|
"text": {
|
|
12755
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."
|
|
12756
13089
|
}
|
|
12757
13090
|
},
|
|
12758
13091
|
"required": [
|
|
@@ -12780,6 +13113,30 @@
|
|
|
12780
13113
|
"completed": {
|
|
12781
13114
|
"type": "boolean",
|
|
12782
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."
|
|
12783
13140
|
}
|
|
12784
13141
|
},
|
|
12785
13142
|
"required": [
|
|
@@ -12787,6 +13144,74 @@
|
|
|
12787
13144
|
]
|
|
12788
13145
|
}
|
|
12789
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
|
+
},
|
|
12790
13215
|
"owner_id": {
|
|
12791
13216
|
"type": "string",
|
|
12792
13217
|
"description": "User UUID to assign as owner. MUTUALLY EXCLUSIVE with owner_team_id. Use listAssignablePrincipals(projectId, kind='user') to look up valid UUIDs."
|
|
@@ -12816,6 +13241,14 @@
|
|
|
12816
13241
|
"percent_complete": {
|
|
12817
13242
|
"type": "number",
|
|
12818
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."
|
|
12819
13252
|
}
|
|
12820
13253
|
},
|
|
12821
13254
|
"required": [
|
|
@@ -13057,8 +13490,13 @@
|
|
|
13057
13490
|
"schema": {
|
|
13058
13491
|
"type": "object",
|
|
13059
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
|
+
},
|
|
13060
13497
|
"taskId": {
|
|
13061
|
-
"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."
|
|
13062
13500
|
}
|
|
13063
13501
|
},
|
|
13064
13502
|
"required": [
|
|
@@ -13146,7 +13584,7 @@
|
|
|
13146
13584
|
"/tools/updateTask": {
|
|
13147
13585
|
"post": {
|
|
13148
13586
|
"summary": "updateTask",
|
|
13149
|
-
"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.",
|
|
13150
13588
|
"operationId": "updateTask",
|
|
13151
13589
|
"tags": [
|
|
13152
13590
|
"plans"
|
|
@@ -13158,6 +13596,10 @@
|
|
|
13158
13596
|
"schema": {
|
|
13159
13597
|
"type": "object",
|
|
13160
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
|
+
},
|
|
13161
13603
|
"taskId": {
|
|
13162
13604
|
"type": "string"
|
|
13163
13605
|
},
|
|
@@ -13246,6 +13688,18 @@
|
|
|
13246
13688
|
},
|
|
13247
13689
|
"text": {
|
|
13248
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."
|
|
13249
13703
|
}
|
|
13250
13704
|
},
|
|
13251
13705
|
"required": [
|
|
@@ -13273,6 +13727,30 @@
|
|
|
13273
13727
|
"completed": {
|
|
13274
13728
|
"type": "boolean",
|
|
13275
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."
|
|
13276
13754
|
}
|
|
13277
13755
|
},
|
|
13278
13756
|
"required": [
|
|
@@ -13370,14 +13848,19 @@
|
|
|
13370
13848
|
},
|
|
13371
13849
|
"reopened_comment": {
|
|
13372
13850
|
"type": "string",
|
|
13373
|
-
"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."
|
|
13374
13852
|
},
|
|
13375
13853
|
"relationships": {
|
|
13376
13854
|
"type": "object",
|
|
13377
|
-
"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."
|
|
13378
13856
|
},
|
|
13379
13857
|
"metadata": {
|
|
13380
|
-
"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."
|
|
13381
13864
|
},
|
|
13382
13865
|
"plan_id": {
|
|
13383
13866
|
"type": "string",
|
|
@@ -13486,8 +13969,13 @@
|
|
|
13486
13969
|
"schema": {
|
|
13487
13970
|
"type": "object",
|
|
13488
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
|
+
},
|
|
13489
13976
|
"planId": {
|
|
13490
|
-
"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."
|
|
13491
13979
|
}
|
|
13492
13980
|
},
|
|
13493
13981
|
"required": [
|
|
@@ -14031,7 +14519,7 @@
|
|
|
14031
14519
|
"/tools/deleteTaskDependency": {
|
|
14032
14520
|
"post": {
|
|
14033
14521
|
"summary": "deleteTaskDependency",
|
|
14034
|
-
"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).",
|
|
14035
14523
|
"operationId": "deleteTaskDependency",
|
|
14036
14524
|
"tags": [
|
|
14037
14525
|
"plans"
|
|
@@ -14588,10 +15076,12 @@
|
|
|
14588
15076
|
"description": "Retrieval strategy. See tool description for when to use each — strongly prefer 'global' for thematic/overview questions."
|
|
14589
15077
|
},
|
|
14590
15078
|
"projectId": {
|
|
14591
|
-
"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."
|
|
14592
15081
|
},
|
|
14593
15082
|
"workspaceId": {
|
|
14594
|
-
"type": "string"
|
|
15083
|
+
"type": "string",
|
|
15084
|
+
"description": "Alternative to projectId — searches the whole workspace subtree. Give one of the two."
|
|
14595
15085
|
},
|
|
14596
15086
|
"srcEntityId": {
|
|
14597
15087
|
"type": "string",
|
|
@@ -14815,6 +15305,10 @@
|
|
|
14815
15305
|
},
|
|
14816
15306
|
"name": {
|
|
14817
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."
|
|
14818
15312
|
}
|
|
14819
15313
|
}
|
|
14820
15314
|
}
|