---
title: "Edit the plan's waiting workflow proposal (creator only)"
method: PATCH
path: "/agents/sessions/{session_id}/plan/proposal"
tags: ["AI", "Agents"]
---

# Edit the plan's waiting workflow proposal (creator only)

`PATCH /agents/sessions/{session_id}/plan/proposal`

## Request

- Base URL: `https://app.mammoth.io/api/v2`
- URL: `https://app.mammoth.io/api/v2/agents/sessions/{session_id}/plan/proposal`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-KEY` and API key in header `X-API-SECRET` and API key in header `X-WORKSPACE-ID`

Body: `plan_id`, `action` (`rename` a new view or dataset to `name`, or `remove` a proposed change and what builds on it) and the change's `key`. Only before the plan is approved; 409 while a turn runs. Returns the plan.

## Path parameters

- `session_id` string, required

## Request body

- EditProposalRequest
  - `plan_id` string, required
  - `action` 'rename' | 'remove', required
  - `key` string, required
  - `name` string, nullable

## Response `200`

Request fulfilled, document follows

- EditProposalResponse
  - `plan` Plan, required
    - `schema_version` 1
    - `plan_id` string, required
    - `revision` integer, required
    - `kind` 'recommendation' | 'execution', required
    - `goal` string, required
    - `steps` PlanStep[], required
      - `n` integer, required
      - `title` string, required
      - `why` string, nullable
      - `touches` ObjectRef[]
        - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'project' | 'file' | 'folder', required
        - `id` integer, nullable
        - `of_step` integer, nullable: The `n` of the earlier step that makes this object (its `makes` has this `kind`), instead of an `id`, for an object that does not exist yet.
        - `name` string
        - `project_id` integer, nullable
        - `project` string
      - `reads` ObjectRef[]
        - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'project' | 'file' | 'folder', required
        - `id` integer, nullable
        - `of_step` integer, nullable: The `n` of the earlier step that makes this object (its `makes` has this `kind`), instead of an `id`, for an object that does not exist yet.
        - `name` string
        - `project_id` integer, nullable
        - `project` string
      - `makes` string[]
      - `names` string[]
      - `renames` Rename[]
        - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'automation' | 'project', required
        - `requested` string, required
        - `final` string, required
      - `workflow_ops` object[]
      - `workflow_changes` object[]
      - `needs` string, nullable
      - `status` 'proposed' | 'approved' | 'in_progress' | 'done' | 'skipped' | 'failed' | 'blocked' | 'stopped', required
      - `result` string, nullable
      - `produced` ObjectRef[]
        - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'project' | 'file' | 'folder', required
        - `id` integer, nullable
        - `of_step` integer, nullable: The `n` of the earlier step that makes this object (its `makes` has this `kind`), instead of an `id`, for an object that does not exist yet.
        - `name` string
        - `project_id` integer, nullable
        - `project` string
      - `changed` ObjectRef[]
        - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'project' | 'file' | 'folder', required
        - `id` integer, nullable
        - `of_step` integer, nullable: The `n` of the earlier step that makes this object (its `makes` has this `kind`), instead of an `id`, for an object that does not exist yet.
        - `name` string
        - `project_id` integer, nullable
        - `project` string
      - `by` 'agent' | 'user'
      - `after` integer[], nullable
      - `replaced` boolean
      - `since_revision` integer, nullable
      - `wait` StepWait
        - `job` string, nullable: The id of a job already started, e.g. "4821".
        - `until` string, date-time, nullable: An ISO 8601 UTC time, e.g. "2026-10-05T03:00:00Z".
      - `skipped_by` 'user' | 'left_out' | 'null', nullable
      - `failed_at` string, date-time, nullable
      - `row_effect` object, nullable
      - `alert_effect` object, nullable
      - `join_effect` object, nullable
      - `send_effect` object, nullable
      - `credentials` ConnectorCredentialInput
        - `auth_type` string, required: The connector's authentication scheme, e.g. 'api_key', 'oauth2', 'basic'. Used only to route the submitted values, never rendered as a label.
        - `fields` CredentialField[], required: The credential fields to collect, in the order they should appear — e.g. [{'name': 'api_key', 'label': 'API key'}]. Name every field the connector actually needs; never include one whose value you already have. Do not include a 'value' — this card never carries one.
          - `name` string, required
          - `label` string
          - `sensitive` boolean
          - `required` boolean: True when the connector cannot be created without this field, e.g. a username or password. The card marks every other field optional and keeps Connect disabled until each required one is filled.
      - `credentials_needed` boolean
    - `supersedes` string, nullable
    - `request_kind` 'build' | 'automate' | 'fix', nullable
    - `workflow_id` integer, nullable
    - `workflow_build` WorkflowBuild
      - `run_id` string, required
      - `keys` string[], required
      - `status` 'running' | 'done' | 'partial' | 'failed'
      - `message` string, nullable
      - `built_keys` string[]
      - `final` object
      - `run` BuildRun
        - `id` string, required
        - `status` string, nullable
        - `started_at` string, nullable
        - `finished_at` string, nullable
        - `steps` BuildRunStep[]
          - `kind` string, nullable
          - `label` string, nullable
          - `keys` string[]
          - `status` string, nullable
          - `started_at` string, nullable
          - `progressed_at` string, nullable
          - `finished_at` string, nullable
          - `result` object, nullable
    - `scope_project` EffectObject
      - `kind` string, required
      - `id` integer, nullable
      - `name` string
      - `project_id` integer, nullable
      - `project` string
    - `worked_after_failure` integer[]
    - `assumptions` string[]
    - `combined_effect` object, nullable
    - `effect` PlanEffect, required: What the plan does, for the plan card (see ``plan_effect``).
      - `steps` StepEffect[], required
        - `n` integer, required
        - `kind` 'read' | 'make' | 'change' | 'deferred', required
        - `status` 'proposed' | 'approved' | 'in_progress' | 'done' | 'skipped' | 'failed' | 'blocked' | 'stopped', required
        - `made` EffectObject[], required
          - `kind` string, required
          - `id` integer, nullable
          - `name` string
          - `project_id` integer, nullable
          - `project` string
        - `changed` EffectObject[], required
          - `kind` string, required
          - `id` integer, nullable
          - `name` string
          - `project_id` integer, nullable
          - `project` string
        - `project_id` integer, nullable
        - `project` string
      - `makes` object, required
      - `new_projects` integer, required
      - `changes` integer, required
      - `project` string, nullable
      - `changes_project` string, nullable
      - `may_change` boolean, required
      - `may_change_in` string, nullable
      - `gates` string[]
      - `gate_target` string
    - `example` boolean, required: Whether the plan is an example workflow (Show me): a recommendation whose steps carry workflow changes. It is previewed, never built.

## Other responses

- `400`: Bad request syntax or unsupported method
- `403`: Request forbidden -- authorization will not help

---

[API](https://skmtc.dev/mammoth/apis/mammoth-analytics.md) · [All operations](https://skmtc.dev/mammoth/apis/mammoth-analytics/llms.txt) · [OpenAPI document](https://skmtc.dev/mammoth/apis/mammoth-analytics/revisions/fe078afe239b?raw)