# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Clickup Goals API
  version: 1.0.0
extends: openapi/clickup-goals-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 16
- target: $.paths['/v2/team/{team_id}/goal'].get
  update:
    x-apievangelist-phrasing:
      intent: List the Goals in a Workspace (v2)
      effect: read
      questions:
      - What Goals does my Workspace have, according to the v2 endpoint?
      - Can the v2 Goals listing include completed Goals?
      instructions:
      - text: Via v2, list Goals in Workspace {team_id}.
        slots:
          team_id: path.team_id
      - text: Using v2, show all Goals in Workspace {team_id} including completed ones.
        slots:
          team_id: path.team_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/team/{team_id}/goal'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Goal (v2)
      effect: write
      questions:
      - How do I set up a new Goal with owners and a due date through v2?
      - Which fields does the v2 create-Goal call require?
      instructions:
      - text: Via v2, create Goal {name} in Workspace {team_id} due {due_date}, owned by {owners}, color {color}.
        slots:
          name: requestBody.name
          team_id: path.team_id
          due_date: requestBody.due_date
          owners: requestBody.owners
          color: requestBody.color
      - text: Using v2, add Goal {name} to Workspace {team_id} due {due_date}.
        slots:
          name: requestBody.name
          team_id: path.team_id
          due_date: requestBody.due_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/goal/{goal_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Goal and its Targets (v2)
      effect: read
      questions:
      - How can I see a single Goal's Targets through v2?
      - Does the v2 Goal lookup return its Targets?
      instructions:
      - text: Via v2, get Goal {goal_id} with its Targets.
        slots:
          goal_id: path.goal_id
      - text: Using v2, show details of Goal {goal_id}.
        slots:
          goal_id: path.goal_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/goal/{goal_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a Goal (v2)
      effect: write
      questions:
      - How do I rename a Goal or change its due date via v2?
      - Can I add and remove Goal owners in the same v2 update?
      instructions:
      - text: Via v2, rename Goal {goal_id} to {name}, due {due_date}, description {description}, color {color}.
        slots:
          goal_id: path.goal_id
          name: requestBody.name
          due_date: requestBody.due_date
          description: requestBody.description
          color: requestBody.color
      - text: Using v2, add owners {add_owners} and remove owners {rem_owners} on Goal {goal_id}.
        slots:
          add_owners: requestBody.add_owners
          rem_owners: requestBody.rem_owners
          goal_id: path.goal_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/goal/{goal_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Goal (v2)
      effect: destructive
      questions:
      - What's the v2 endpoint for removing a Goal from my Workspace?
      - Can I delete a Goal by ID via v2?
      instructions:
      - text: Via v2, delete Goal {goal_id}.
        slots:
          goal_id: path.goal_id
      - text: Using v2, remove Goal {goal_id} from the Workspace.
        slots:
          goal_id: path.goal_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/goal/{goal_id}/key_result'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a Target to a Goal (v2)
      effect: write
      questions:
      - How do I add a measurable Target to a Goal through v2?
      - Can a v2 Target track progress from specific tasks or Lists?
      instructions:
      - text: Via v2, add Target {name} of type {type} to Goal {goal_id}, owners {owners}, from {steps_start} to {steps_end} {unit}, tasks {task_ids}, Lists {list_ids}.
        slots:
          name: requestBody.name
          type: requestBody.type
          goal_id: path.goal_id
          owners: requestBody.owners
          steps_start: requestBody.steps_start
          steps_end: requestBody.steps_end
          unit: requestBody.unit
          task_ids: requestBody.task_ids
          list_ids: requestBody.list_ids
      - text: Using v2, create a {type} Target called {name} on Goal {goal_id}.
        slots:
          type: requestBody.type
          name: requestBody.name
          goal_id: path.goal_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/key_result/{key_result_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a Target's progress (v2)
      effect: write
      questions:
      - How do I record progress on a Goal Target through v2?
      - Can I leave a note when updating a Target in v2?
      instructions:
      - text: Via v2, set Target {key_result_id} current progress to {steps_current} with note {note}.
        slots:
          key_result_id: path.key_result_id
          steps_current: requestBody.steps_current
          note: requestBody.note
      - text: Using v2, update Target {key_result_id} to {steps_current}.
        slots:
          key_result_id: path.key_result_id
          steps_current: requestBody.steps_current
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/key_result/{key_result_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Target from a Goal (v2)
      effect: destructive
      questions:
      - What's the v2 way to remove a Target from a Goal?
      - Can I delete a single Target without deleting its Goal via v2?
      instructions:
      - text: Via v2, delete Target {key_result_id}.
        slots:
          key_result_id: path.key_result_id
      - text: Using v2, remove Target {key_result_id} from its Goal.
        slots:
          key_result_id: path.key_result_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/team/{team_id}/goal'].get
  update:
    x-apievangelist-phrasing:
      intent: List Goals with progress (unversioned path)
      effect: read
      questions:
      - Which non-v2 endpoint lists Goals with their key results and progress?
      - Can the unversioned Goals listing include completed Goals?
      instructions:
      - text: Using the unversioned path, list Goals in Workspace {team_id}.
        slots:
          team_id: path.team_id
      - text: On the non-v2 endpoint, show Goal progress for Workspace {team_id}.
        slots:
          team_id: path.team_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/team/{team_id}/goal'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Goal (unversioned path)
      effect: write
      questions:
      - Is there a non-v2 path to create a Goal with only a name and due date?
      - Can I set a Goal's color on the unversioned create endpoint?
      instructions:
      - text: Using the unversioned path, create Goal {name} in Workspace {team_id} due {due_date}.
        slots:
          name: requestBody.name
          team_id: path.team_id
          due_date: requestBody.due_date
      - text: On the non-v2 endpoint, add Goal {name} to Workspace {team_id} due {due_date} with color {color}.
        slots:
          name: requestBody.name
          team_id: path.team_id
          due_date: requestBody.due_date
          color: requestBody.color
      method: generated
      generated: '2026-09-26'
- target: $.paths['/goal/{goal_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Goal's key results and progress (unversioned)
      effect: read
      questions:
      - Which non-v2 endpoint shows one Goal's key results and progress?
      - Can I look up a Goal on the unversioned path?
      instructions:
      - text: Using the unversioned path, get Goal {goal_id}.
        slots:
          goal_id: path.goal_id
      - text: On the non-v2 endpoint, show key results and progress of Goal {goal_id}.
        slots:
          goal_id: path.goal_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/goal/{goal_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a Goal (unversioned path)
      effect: write
      questions:
      - Is there a non-v2 path for changing only a Goal's name?
      - Can I update a Goal's owners through the unversioned endpoint?
      instructions:
      - text: Using the unversioned path, rename Goal {goal_id} to {name}.
        slots:
          goal_id: path.goal_id
          name: requestBody.name
      - text: On the non-v2 endpoint, add owners {add_owners} to Goal {goal_id}.
        slots:
          add_owners: requestBody.add_owners
          goal_id: path.goal_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/goal/{goal_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Goal and its key results (unversioned)
      effect: destructive
      questions:
      - Does deleting a Goal on the non-v2 path also delete its key results?
      - Is removing a Goal through the unversioned endpoint permanent?
      instructions:
      - text: Using the unversioned path, permanently delete Goal {goal_id} and its key results.
        slots:
          goal_id: path.goal_id
      - text: On the non-v2 endpoint, remove Goal {goal_id} for good.
        slots:
          goal_id: path.goal_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/goal/{goal_id}/key_result'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a key result on a Goal (unversioned)
      effect: write
      questions:
      - Which key result types can I create on the non-v2 path, like currency or percentage?
      - Can a key result on the unversioned endpoint track task completion automatically?
      instructions:
      - text: Using the unversioned path, create a {type} key result named {name} on Goal {goal_id}.
        slots:
          type: requestBody.type
          name: requestBody.name
          goal_id: path.goal_id
      - text: On the non-v2 endpoint, add key result {name} of type {type} to Goal {goal_id} targeting {steps_end}.
        slots:
          name: requestBody.name
          type: requestBody.type
          goal_id: path.goal_id
          steps_end: requestBody.steps_end
      method: generated
      generated: '2026-09-26'
- target: $.paths['/key_result/{key_result_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a key result (unversioned path)
      effect: write
      questions:
      - Is there a non-v2 path to update a key result's progress?
      - Can I add a note to a key result on the unversioned endpoint?
      instructions:
      - text: Using the unversioned path, set key result {key_result_id} progress to {steps_current}.
        slots:
          key_result_id: path.key_result_id
          steps_current: requestBody.steps_current
      - text: On the non-v2 endpoint, add note {note} to key result {key_result_id}.
        slots:
          note: requestBody.note
          key_result_id: path.key_result_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/key_result/{key_result_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a key result (unversioned path)
      effect: destructive
      questions:
      - Which non-v2 endpoint permanently deletes a key result?
      - Can I remove a key result through the unversioned path?
      instructions:
      - text: Using the unversioned path, permanently delete key result {key_result_id}.
        slots:
          key_result_id: path.key_result_id
      - text: On the non-v2 endpoint, remove key result {key_result_id} from its Goal.
        slots:
          key_result_id: path.key_result_id
      method: generated
      generated: '2026-09-26'