Plans & Playbooks

update_plan

Partial update of a plan: mutable fields and stage transitions.

Input Schema

{
  "type": "object",
  "required": [
    "plan_uuid"
  ],
  "properties": {
    "title": {
      "type": "string",
      "description": "Update plan title (1-200 chars)."
    },
    "prompt": {
      "type": "string",
      "description": "Update the content prompt."
    },
    "due_date": {
      "type": "string",
      "description": "Update due date (ISO YYYY-MM-DD). null is currently IGNORED (no-op); clearing ships with the null-accept backend change."
    },
    "plan_uuid": {
      "type": "string",
      "description": "Required. UUID of the plan to update."
    },
    "project_id": {
      "type": "string",
      "description": "Update project association. null is currently IGNORED (no-op); clearing ships with the null-accept backend change."
    },
    "visibility": {
      "enum": [
        "private",
        "team"
      ],
      "type": "string",
      "description": "Change the plan's visibility. Creator-only — non-creators get InputError."
    },
    "assigned_to": {
      "type": "integer",
      "description": "Reassign to a different team member (integer user ID). Must be a current team member. Assigning a private plan to anyone other than the calling user auto-promotes it to team visibility."
    },
    "category_id": {
      "type": "integer",
      "description": "Update category association. null is currently IGNORED (no-op); clearing ships with the null-accept backend change."
    },
    "description": {
      "type": "string",
      "description": "Update plan description."
    },
    "blueprint_id": {
      "type": "string",
      "description": "Update blueprint association — accepts a blueprint UUID (from list_blueprints) or integer id. null is currently IGNORED (no-op); clearing ships with the null-accept backend change."
    },
    "target_stage": {
      "type": "string",
      "description": "Request a stage transition. Use UNDERSCORE form In_Process. Validated against the allowed-transition map; disallowed transitions return InputError. Allowed: Suggested, Accepted, In_Process, Complete, Dismissed."
    },
    "context_collection_ids": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "REPLACES full set of context collection associations. Pass [] to clear all."
    },
    "reference_document_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "REPLACES full set of reference doc associations. Pass [] to clear all."
    },
    "targeting_dimension_ids": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "REPLACES full set of targeting dimension associations. Pass [] to clear all."
    }
  }
}

Output Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "stage": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "prompt": {
      "type": [
        "string",
        "null"
      ]
    },
    "source": {
      "type": "string"
    },
    "team_id": {
      "type": "integer"
    },
    "due_date": {
      "type": [
        "string",
        "null"
      ]
    },
    "link_url": {
      "type": "string",
      "format": "uri",
      "description": "Shareable deep-link that opens the plans screen with this plan's detail overlay. Give this to the user."
    },
    "plan_uuid": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    },
    "created_by": {
      "type": "integer"
    },
    "project_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "updated_at": {
      "type": "string"
    },
    "visibility": {
      "enum": [
        "private",
        "team"
      ],
      "type": "string",
      "description": "private = creator-only; team = visible to all active teammates."
    },
    "assigned_to": {
      "type": "integer"
    },
    "category_id": {
      "type": [
        "integer",
        "null"
      ]
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "blueprint_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "completed_at": {
      "type": [
        "integer",
        "null"
      ]
    },
    "dismissed_at": {
      "type": [
        "integer",
        "null"
      ]
    },
    "source_metadata": {
      "type": [
        "object",
        "null"
      ]
    },
    "context_collections": {
      "type": "array"
    },
    "produced_content_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "reference_documents": {
      "type": "array"
    },
    "targeting_dimensions": {
      "type": "array"
    }
  },
  "description": "Updated plan object with all fields."
}

Instructions

Performs a partial update on a plan. All fields are optional — supply only what you want to change.

Array fields replace entirely: reference_document_ids, context_collection_ids, and targeting_dimension_ids REPLACE the full set when provided. Pass an empty array [] to clear all associations.

Nullable fields: Pass null to clear blueprint_id, project_id, category_id, and due_date.

Stage transitions (use target_stage):

Suggested -> Accepted or Dismissed
Accepted -> In_Process or Dismissed
In_Process -> Complete, Accepted, or Dismissed
Complete -> Accepted or Dismissed
Dismissed -> terminal, no further transitions

Use UNDERSCORE form for stage values: In_Process (not In Process).

Note: source and source_metadata are immutable and cannot be updated after creation.