improvements

createImprovement

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. Pass parentItemId to create it under its epic or story in the work hierarchy. Pass fields (for example ["id", "friendlyId", "versionTimestamp"]) for a short answer instead of the whole improvement.

post/tools/createImprovement

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/createImprovement
  • Auth: HTTP bearer

Request body

projectIdstring required
titlestring required
typestring

Type. Default: enhancement. 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). 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; any other type makes it a non-task item. The id's prefix follows the type: epic EPIC-, user_story STY-, requirement REQ-, test_case TC-, spike SPK-, task TAS-; every other type IMP-. The number is shared by every type and never changes: a type change rewrites only the prefix (STY-30 becomes IMP-30), and the old id still resolves. Types with fields of their own (epic, user_story, requirement, test_case, spike) take them in details.

parentItemIdstring

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.

prioritystring

Priority. Default: medium.

status'captured' | 'triaging' | 'shaped' | 'approved' | 'ready_for_agent' | 'in_progress' | 'ready_for_review' | 'in_review' | 'blocked' | 'done' | 'rejected' | 'deferred'

Initial status. Default: captured.

source'human_manual' | 'agent_review' | 'doc_comment' | 'feedback' | 'incident' | 'postmortem' | 'code_review' | 'imported'

Where the work came from. Default: human_manual (shown as a general item), which is right for anything you raise yourself. Use feedback, incident, postmortem, code_review, doc_comment or imported when the item came from one of those. agent_review files the item under Compliance in the register: use it only for a compliance finding.

urgencystring

e.g. this_week, this_month, this_quarter.

category_idstring

Category ID.

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

Array of {id, title}.

linked_document_idsstring[]

Document IDs to link. Titles resolved automatically.

impacted_diagramsobject[]

Array of {id, name}.

impacted_componentsstring[]
agent_readyboolean
agent_missing_infostring[]
agent_recommended_actionstring
agent_complexitystring

low, medium, high, very_high.

agent_confidencenumber

0.00 to 1.00.

agent_briefstring
target_datestring

YYYY-MM-DD.

start_datestring

YYYY-MM-DD.

end_datestring

YYYY-MM-DD.

owner_idstring

User UUID to assign as the owner. MUTUALLY EXCLUSIVE with owner_team_id — set one or the other, never both. Use listAssignablePrincipals(projectId, kind='user', q='…') to look up valid user UUIDs.

owner_team_idstring

Team UUID to assign as the owner (assigns the whole team rather than an individual). MUTUALLY EXCLUSIVE with owner_id. Use listTeams(workspaceId) or listAssignablePrincipals(projectId, kind='team') to look up valid team UUIDs.

plan_idstring

Link to a plan.

phase_idstring

Assign to a phase.

is_taskboolean

Mark as task. Default: false. Prefer setting type='task' instead: is_task follows the type automatically, and the friendly id's prefix follows the type too (see type).

descriptionstring
wbs_codestring

Work breakdown structure code.

percent_completenumber

Progress percentage (0-100). Null means not tracked.

source_channelstring
impacted_repositoriesstring[]
relationshipsobject

Free-form JSON for logical links: blocks, blocked_by, duplicates, supersedes, relates_to (arrays of item IDs).

metadataobject

Free-form JSON stored alongside the item. On updateImprovement this MERGES rather than replaces.

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.