# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Asana Goals API
  version: 1.0.0
extends: openapi/asana-goals-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 10
- target: $.paths['/goals/{goal_gid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a goal's details
      effect: read
      questions:
      - What does the full record of a goal show?
      - Can I look up a goal's owner, status and metric by ID?
      instructions:
      - text: Show the details of goal {goal}.
        slots:
          goal: path.goal_gid
      - text: Fetch goal {goal}.
        slots:
          goal: path.goal_gid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/goals/{goal_gid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a goal
      effect: write
      questions:
      - How do I change a goal's status, owner or due date?
      - Do fields I leave out of a goal update stay the same?
      instructions:
      - text: Set goal {goal}'s status to {status}.
        slots:
          goal: path.goal_gid
          status: requestBody.data
      - text: Update goal {goal} with {changes}.
        slots:
          goal: path.goal_gid
          changes: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/goals/{goal_gid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a goal
      effect: destructive
      questions:
      - Can I delete a goal that's no longer relevant?
      - What does deleting a goal return?
      instructions:
      - text: Delete goal {goal}.
        slots:
          goal: path.goal_gid
      - text: Remove goal {goal} permanently.
        slots:
          goal: path.goal_gid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/goals'].get
  update:
    x-apievangelist-phrasing:
      intent: List goals by team, project or time period
      effect: read
      questions:
      - Which goals does a team have this quarter?
      - Can I list only workspace-level goals?
      - How do I find the goals tied to a portfolio or project?
      instructions:
      - text: List goals for team {team} in time periods {periods}.
        slots:
          team: query.team
          periods: query.time_periods
      - text: Show workspace-level goals in workspace {workspace}.
        slots:
          workspace: query.workspace
      - text: List the goals linked to project {project}.
        slots:
          project: query.project
      method: generated
      generated: '2026-10-01'
- target: $.paths['/goals'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a goal
      effect: write
      questions:
      - How do I create a new goal for my team?
      - Can a goal be created at the workspace level instead of under a team?
      instructions:
      - text: Create a goal named {goal} in my workspace.
        slots:
          goal: requestBody.data
      - text: Set a new team goal with {fields}.
        slots:
          fields: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/goals/{goal_gid}/setMetric'].post
  update:
    x-apievangelist-phrasing:
      intent: Set the metric that tracks a goal
      effect: write
      questions:
      - How do I attach a numeric target to a goal?
      - Will setting a metric replace one the goal already has?
      instructions:
      - text: Set a metric on goal {goal} with target {metric}.
        slots:
          goal: path.goal_gid
          metric: requestBody.data
      - text: Replace goal {goal}'s metric with {metric}.
        slots:
          goal: path.goal_gid
          metric: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/goals/{goal_gid}/setMetricCurrentValue'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a goal metric's current value
      effect: write
      questions:
      - How do I report progress on a goal's metric?
      - What happens if I update the current value on a goal with no metric?
      instructions:
      - text: Set goal {goal}'s current metric value to {value}.
        slots:
          goal: path.goal_gid
          value: requestBody.data
      - text: Record progress of {value} on goal {goal}.
        slots:
          goal: path.goal_gid
          value: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/goals/{goal_gid}/addFollowers'].post
  update:
    x-apievangelist-phrasing:
      intent: Add collaborators to a goal
      effect: write
      questions:
      - How do I add collaborators to a goal?
      - Can several people follow a goal?
      instructions:
      - text: Add collaborators {followers} to goal {goal}.
        slots:
          goal: path.goal_gid
          followers: requestBody.data
      - text: Have {followers} follow goal {goal}.
        slots:
          goal: path.goal_gid
          followers: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/goals/{goal_gid}/removeFollowers'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove collaborators from a goal
      effect: write
      questions:
      - Can I take a collaborator off a goal?
      - How do I stop people following a goal?
      instructions:
      - text: Remove collaborators {followers} from goal {goal}.
        slots:
          goal: path.goal_gid
          followers: requestBody.data
      - text: Stop {followers} following goal {goal}.
        slots:
          goal: path.goal_gid
          followers: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/goals/{goal_gid}/parentGoals'].get
  update:
    x-apievangelist-phrasing:
      intent: List a goal's parent goals
      effect: read
      questions:
      - Which higher-level goals does this goal roll up to?
      - Can I see the parent goals of a goal?
      instructions:
      - text: List the parent goals of goal {goal}.
        slots:
          goal: path.goal_gid
      - text: Show what goal {goal} rolls up into.
        slots:
          goal: path.goal_gid
      method: generated
      generated: '2026-10-01'