manage_bar
Create, update, or delete roadmap bars by adding features, adjusting dates, changing colors, or nesting items. Handles single-bar changes with precise field control.
Instructions
Create, update, or delete a bar on a roadmap.
USE WHEN: "Add feature", "Update dates", "Delete item", "Change color", "Nest this bar under that one" For many bars at once (e.g. "color these 30 bars"), use bulk_update_bars, bulk_create_bars, or bulk_delete_bars instead. Actions: create (roadmap_id + name + lane or lane_id), update (bar_id + any fields), delete (bar_id) Color a bar with legend (a legend NAME from get_roadmap_legends); legend:"" or clear_legend:true removes the color. Omitted fields are never sent, so an update only touches what you pass. New bars are parked (off the timeline) by ProductPlan's default. When you give starts_on and ends_on on create and leave parked unset, the bar defaults to parked:false so it lands on the timeline; a nested bar inherits its container's parked state. Names (legend, lane, custom field labels, dropdown values) are checked against the roadmap before writing, matched case-insensitively, and sent in canonical spelling. Returns: create gives the new bar's id plus the bar read back; update gives the exact fields sent. FAILS WHEN: create without roadmap_id, name, or a lane; update/delete without bar_id; a legend, lane, or custom field name is not on the roadmap (the error lists the valid ones); container_bar_id on a bar without both dates, or a parked state that differs from the container's. legend_id and effort are rejected with an explanation (legend_id would wipe the bar's color). A bar cannot be un-nested via the API once container_bar_id is set. WARNING: delete is permanent and cannot be undone.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lane | No | Lane NAME (see get_roadmap lanes). Use this or lane_id | |
| name | No | Bar name | |
| tags | No | Tag strings; REPLACES the bar's tag list. [] clears it | |
| notes | No | Additional notes | |
| action | Yes | create, update, or delete | |
| bar_id | No | Bar ID (for update/delete) | |
| effort | No | DEPRECATED and rejected: not a ProductPlan bar field (the API ignores it). Use a custom field | |
| legend | No | Legend NAME that colors the bar (from get_roadmap_legends). Empty string clears the color | |
| parked | No | True parks the bar (off the timeline, kept on the roadmap). Must match the container's when nested | |
| ends_on | No | End date YYYY-MM-DD | |
| lane_id | No | Lane ID from get_roadmap_lanes. Use this or lane | |
| container | No | DEPRECATED alias for is_container | |
| legend_id | No | DEPRECATED and rejected: the API reads legend_id as 'clear the color'. Use legend (name) | |
| parent_id | No | DEPRECATED alias for container_bar_id | |
| starts_on | No | Start date YYYY-MM-DD | |
| roadmap_id | No | Roadmap ID (required for create; optional on update to skip looking up the bar's roadmap) | |
| description | No | Description (markdown) | |
| clear_legend | No | True to remove the bar's color (same as legend:"") | |
| is_container | No | True to make the bar a container for child bars | |
| percent_done | No | Progress 0-100 | |
| strategic_value | No | Free-text strategic importance note | |
| container_bar_id | No | Numeric ID of the container bar to nest under. Requires starts_on and ends_on on the bar; cannot be removed once set | |
| custom_text_fields | No | [{label,value}] using labels from get_roadmap custom_text_fields | |
| custom_dropdown_fields | No | [{label,value}]; value must be one of the field's allowed_values from get_roadmap |