# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Asana Portfolios API
  version: 1.0.0
extends: openapi/asana-portfolios-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: 12
- target: $.paths['/portfolios'].get
  update:
    x-apievangelist-phrasing:
      intent: List portfolios I own in a workspace
      effect: read
      questions:
      - Which portfolios do I own in a workspace?
      - Can I list portfolios for a specific owner?
      instructions:
      - text: List my portfolios in workspace {workspace}.
        slots:
          workspace: query.workspace
      - text: Show portfolios in workspace {workspace} owned by {owner}.
        slots:
          workspace: query.workspace
          owner: query.owner
      method: generated
      generated: '2026-10-01'
- target: $.paths['/portfolios'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a portfolio
      effect: write
      questions:
      - How do I create a portfolio in Asana?
      - Do portfolios made through the API get the same default views as ones made in the UI?
      instructions:
      - text: Create a portfolio named {portfolio} in my workspace.
        slots:
          portfolio: requestBody.data
      - text: Set up a new portfolio with {fields}.
        slots:
          fields: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/portfolios/{portfolio_gid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a portfolio's details
      effect: read
      questions:
      - What's in the full record of a portfolio?
      - Can I look up a portfolio's owner and color by ID?
      instructions:
      - text: Show the details of portfolio {portfolio}.
        slots:
          portfolio: path.portfolio_gid
      - text: Fetch portfolio {portfolio}.
        slots:
          portfolio: path.portfolio_gid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/portfolios/{portfolio_gid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a portfolio
      effect: write
      questions:
      - Can I rename a portfolio or change its color?
      - Which portfolio fields stay unchanged when I send a partial update?
      instructions:
      - text: Rename portfolio {portfolio} to {name}.
        slots:
          portfolio: path.portfolio_gid
          name: requestBody.data
      - text: Update portfolio {portfolio} with {changes}.
        slots:
          portfolio: path.portfolio_gid
          changes: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/portfolios/{portfolio_gid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a portfolio
      effect: destructive
      questions:
      - Can I delete a portfolio I no longer use?
      - What does deleting a portfolio return?
      instructions:
      - text: Delete portfolio {portfolio}.
        slots:
          portfolio: path.portfolio_gid
      - text: Remove portfolio {portfolio} permanently.
        slots:
          portfolio: path.portfolio_gid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/portfolios/{portfolio_gid}/items'].get
  update:
    x-apievangelist-phrasing:
      intent: List the projects in a portfolio
      effect: read
      questions:
      - Which projects are inside a portfolio?
      - Can I page through a portfolio's items?
      instructions:
      - text: List the items in portfolio {portfolio}.
        slots:
          portfolio: path.portfolio_gid
      - text: Show the projects tracked by portfolio {portfolio}.
        slots:
          portfolio: path.portfolio_gid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/portfolios/{portfolio_gid}/addItem'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a project to a portfolio
      effect: write
      questions:
      - How do I put a project into a portfolio?
      - Can I control where an item lands in a portfolio's order?
      instructions:
      - text: Add project {item} to portfolio {portfolio}.
        slots:
          portfolio: path.portfolio_gid
          item: requestBody.data
      - text: Track item {item} in portfolio {portfolio}.
        slots:
          portfolio: path.portfolio_gid
          item: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/portfolios/{portfolio_gid}/removeItem'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove a project from a portfolio
      effect: write
      questions:
      - Can I take a project out of a portfolio without deleting it?
      - How do I stop tracking an item in a portfolio?
      instructions:
      - text: Remove item {item} from portfolio {portfolio}.
        slots:
          portfolio: path.portfolio_gid
          item: requestBody.data
      - text: Take project {item} out of portfolio {portfolio}.
        slots:
          portfolio: path.portfolio_gid
          item: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/portfolios/{portfolio_gid}/addCustomFieldSetting'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a custom field to a portfolio
      effect: write
      questions:
      - How do I add a custom field column to a portfolio?
      - Can portfolios have their own custom fields?
      instructions:
      - text: Add custom field {custom_field} to portfolio {portfolio}.
        slots:
          portfolio: path.portfolio_gid
          custom_field: requestBody.data
      - text: Attach field {custom_field} to portfolio {portfolio}.
        slots:
          portfolio: path.portfolio_gid
          custom_field: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/portfolios/{portfolio_gid}/removeCustomFieldSetting'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove a custom field from a portfolio
      effect: write
      questions:
      - Can I detach a custom field from a portfolio?
      - What's the way to drop a field column from a portfolio?
      instructions:
      - text: Remove custom field {custom_field} from portfolio {portfolio}.
        slots:
          portfolio: path.portfolio_gid
          custom_field: requestBody.data
      - text: Detach field {custom_field} from portfolio {portfolio}.
        slots:
          portfolio: path.portfolio_gid
          custom_field: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/portfolios/{portfolio_gid}/addMembers'].post
  update:
    x-apievangelist-phrasing:
      intent: Add users to a portfolio
      effect: write
      questions:
      - How do I share a portfolio with teammates?
      - Can I add several users to a portfolio at once?
      instructions:
      - text: Add users {users} to portfolio {portfolio}.
        slots:
          portfolio: path.portfolio_gid
          users: requestBody.data
      - text: Share portfolio {portfolio} with members {users}.
        slots:
          portfolio: path.portfolio_gid
          users: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/portfolios/{portfolio_gid}/removeMembers'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove users from a portfolio
      effect: write
      questions:
      - Can I revoke someone's access to a portfolio?
      - What's returned after users are removed from a portfolio?
      instructions:
      - text: Remove users {users} from portfolio {portfolio}.
        slots:
          portfolio: path.portfolio_gid
          users: requestBody.data
      - text: Revoke portfolio {portfolio} access for {users}.
        slots:
          portfolio: path.portfolio_gid
          users: requestBody.data
      method: generated
      generated: '2026-10-01'