improvements

updateImprovement

Update an improvement, or many in one call (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), acceptance_criteria (objects with per-row updated_by/at attribution) and parentItemId (the epic or story it belongs to in the work hierarchy; null removes it). versionTimestamp (optimistic locking) is the item's updated_at in epoch milliseconds, and you rarely need a getImprovement call for it: listImprovements returns it for every improvement in a project (fields ["id", "friendlyId", "versionTimestamp"] keeps that answer short), getPlan (items[].versionTimestamp) for every item in a plan, and every write returns the new one. Pass fields (for example ["id", "versionTimestamp"]) for a short answer instead of the whole record. To change many improvements, send items: up to 200 entries of { improvementId, versionTimestamp, ...changes } per call (more than 200: split them into several calls of up to 200), each checked and written on its own and answered with one row per entry plus a summary. 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: an item has one owner, a user or a team, never both). 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.

post/tools/updateImprovement

Request

  • Base URL: https://api.stablebaseline.io/functions/v1/cloud-serve/api/v1
  • URL: https://api.stablebaseline.io/functions/v1/cloud-serve/api/v1/tools/updateImprovement
  • Auth: HTTP bearer

Request body

projectIdstring

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.

planIdstring

Optional. Narrows a friendly-id lookup (such as IMP-42) to one plan, given as the plan's UUID or friendly id (such as PLN-3): the item must be in that plan. It never moves anything (plan_id does that) and is ignored when the id is a UUID.

improvementIdstring

Required unless you send items. The improvement's UUID or friendly id (such as IMP-42).

versionTimestampnumber

Required unless you send items. The item's current versionTimestamp (its updated_at in epoch ms), as listImprovements, getPlan, getImprovement or your last write of it returned.

titlestring
typestring

One of: feature (New capability for users); enhancement (An improvement to something that already exists); bug (Something that does not work as it should); tech_debt (Work that makes the system easier and safer to change); architecture_gap (A missing or weak part of the architecture); documentation_gap (Documentation that is missing or out of date); risk (Something that could go wrong, to track and reduce); epic (A large body of work, delivered through several stories, features or tasks); user_story (A need told from a user's view: as a role, I want a goal, so that a benefit); requirement (A condition or capability the solution must meet, stated so it can be verified); test_case (Steps that verify a requirement or story, each with its expected result); spike (Time-boxed research to answer a question before committing to the work); task (A unit of work in a plan). Changing the type keeps everything written on the item, its parent and children included. The id's prefix follows the type (see createImprovement's type) and its number stays, so the id can change (STY-30 becomes IMP-30 when a story becomes a feature): the answer's note then gives the new id, and the old one still resolves.

parentItemIdstring nullable

The work item this one belongs to in the work hierarchy: an epic for a story, a story for its tasks or test cases. Any item in the same project, in any plan or phase. Not the plan outline nesting, which setPlanItemParent sets. Give its UUID or friendly id (such as IMP-12 or TAS-3). Rules: the same project; no loops (an item cannot sit inside its own children); at most 5 levels, counting this item's own children. null removes the parent.

status'captured' | 'triaging' | 'shaped' | 'approved' | 'ready_for_agent' | 'in_progress' | 'ready_for_review' | 'in_review' | 'blocked' | 'done' | 'rejected' | 'deferred'
prioritystring
urgencystring
owner_idstring nullable

User UUID to assign as owner, or null to unassign. MUTUALLY EXCLUSIVE with owner_team_id — when switching from a user to a team owner, send owner_id: null in the same call as owner_team_id. Use listAssignablePrincipals(projectId, kind='user', q='…') to look up valid UUIDs.

owner_team_idstring nullable

Team UUID to assign as owner, or null to unassign. MUTUALLY EXCLUSIVE with owner_id — when switching from a team to a user owner, send owner_team_id: null in the same call as owner_id. Use listTeams or listAssignablePrincipals(kind='team') to look up valid UUIDs.

target_datestring
start_datestring

YYYY-MM-DD.

end_datestring

YYYY-MM-DD.

category_idstring

Category ID. Null to unassign.

positionnumber
problem_statementstring
desired_outcomestring
business_impactstring
user_impactstring
why_nowstring
constraintsstring[]
non_goalsstring[]
impacted_documentsobject[]
linked_document_idsstring[]

Document IDs to link.

impacted_diagramsobject[]
impacted_componentsstring[]
impacted_repositoriesstring[]
agent_readyboolean
agent_missing_infostring[]
agent_recommended_actionstring
agent_complexitystring
agent_confidencenumber
agent_briefstring
resolution_summarystring
resolution_pr_urlstring
docs_updatedboolean
follow_up_neededboolean
blocked_commentstring

Required when status=blocked.

rejection_commentstring

Required when status=rejected.

completion_commentstring

Required when status=done.

reopened_commentstring

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.

relationshipsobject

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.

metadataobject

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.)

metadata_replaceboolean

Opt out of the metadata merge: true means the object you send REPLACES everything stored, deleting any key you omit. Default false.

plan_idstring

Link to plan. Null to unlink.

phase_idstring

Assign to phase. Null to unassign.

is_taskboolean

Mark as task. Prefer setting type='task' instead: is_task follows the type automatically.

descriptionstring
wbs_codestring
percent_completenumber

Progress percentage (0-100). Null to clear.

fieldsstring[]

Optional. Answer with only these fields instead of the whole improvement, for example ["id", "versionTimestamp"]. Any of the improvement's own fields (snake_case or camelCase) or of the keys around it in the full answer (versionTimestamp, href and, where present, url, title, trackingId, message). The id is always returned, and so is any notice that needs your attention (a note, such as a phase's dates following its tasks or an item's id changing with its type, and a date change's cascadePreview). Unknown names are ignored.

Response

Tool result (shape varies per tool — refer to the tool's docs for the exact return value).

object required

Changes

No recorded changes to this operation across all 1 revision of this API.