# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for cdp-api Funnels API
  version: 1.0.0
extends: openapi/treasure-data-funnels-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: 13
- target: $.paths['/audiences/{audienceId}/funnels'].get
  update:
    x-apievangelist-phrasing:
      intent: List funnels in a parent segment
      effect: read
      questions:
      - What funnels are defined on my parent segment?
      - Can I see all funnels and their stages for a parent segment?
      instructions:
      - text: List funnels in parent segment {audienceId}.
        slots:
          audienceId: path.audienceId
      - text: Show all funnels and their stages for parent segment {audienceId}.
        slots:
          audienceId: path.audienceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/funnels'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a funnel (legacy Audience Studio)
      effect: write
      questions:
      - How do I build a new funnel with stages in legacy Audience Studio?
      - Can I create a funnel inside a specific segment folder?
      instructions:
      - text: Create funnel {name} in parent segment {audienceId} in folder {segmentFolderId} with stages {stages}.
        slots:
          name: requestBody.name
          audienceId: path.audienceId
          segmentFolderId: requestBody.segmentFolderId
          stages: requestBody.stages
      - text: Add a legacy funnel {name} to parent segment {audienceId}, folder {segmentFolderId}, stages {stages}.
        slots:
          name: requestBody.name
          audienceId: path.audienceId
          segmentFolderId: requestBody.segmentFolderId
          stages: requestBody.stages
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/funnels/{funnelId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a funnel by ID
      effect: read
      questions:
      - How do I look at a single funnel's stages?
      - Can I fetch one funnel by its ID?
      instructions:
      - text: Show funnel {funnelId} in parent segment {audienceId}.
        slots:
          funnelId: path.funnelId
          audienceId: path.audienceId
      - text: Get the stages of funnel {funnelId} in parent segment {audienceId}.
        slots:
          funnelId: path.funnelId
          audienceId: path.audienceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/funnels/{funnelId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a funnel (legacy Audience Studio)
      effect: write
      questions:
      - Can I change the stages of an existing funnel?
      - How do I rename a funnel in legacy Audience Studio?
      instructions:
      - text: 'Update funnel {funnelId} in parent segment {audienceId}: name {name}, folder {segmentFolderId}, stages {stages}.'
        slots:
          funnelId: path.funnelId
          audienceId: path.audienceId
          name: requestBody.name
          segmentFolderId: requestBody.segmentFolderId
          stages: requestBody.stages
      - text: Replace the stages of funnel {funnelId} (parent segment {audienceId}) with {stages}, keeping name {name} and folder {segmentFolderId}.
        slots:
          funnelId: path.funnelId
          audienceId: path.audienceId
          stages: requestBody.stages
          name: requestBody.name
          segmentFolderId: requestBody.segmentFolderId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/funnels/{funnelId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a funnel (legacy Audience Studio)
      effect: destructive
      questions:
      - How do I delete a funnel I no longer use?
      - Can I remove a funnel from a parent segment?
      instructions:
      - text: Delete funnel {funnelId} from parent segment {audienceId}.
        slots:
          funnelId: path.funnelId
          audienceId: path.audienceId
      - text: Remove legacy funnel {funnelId} in parent segment {audienceId}.
        slots:
          funnelId: path.funnelId
          audienceId: path.audienceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/funnels/{funnelId}/clone'].post
  update:
    x-apievangelist-phrasing:
      intent: Clone a funnel
      effect: write
      questions:
      - Can I copy an existing funnel as a starting point for a new one?
      - How do I duplicate a funnel into another folder?
      instructions:
      - text: Clone funnel {funnelId} in parent segment {audienceId} as {name} in folder {segmentFolderId}.
        slots:
          funnelId: path.funnelId
          audienceId: path.audienceId
          name: requestBody.name
          segmentFolderId: requestBody.segmentFolderId
      - text: Duplicate funnel {funnelId} of parent segment {audienceId} into a copy named {name} in folder {segmentFolderId}.
        slots:
          funnelId: path.funnelId
          audienceId: path.audienceId
          name: requestBody.name
          segmentFolderId: requestBody.segmentFolderId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audiences/{audienceId}/funnels/{funnelId}/statistics'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a funnel's daily population history
      effect: read
      questions:
      - How many profiles were in each funnel stage over time?
      - Can I get funnel population stats for a date range?
      instructions:
      - text: Show population history of funnel {funnelId} in parent segment {audienceId}.
        slots:
          funnelId: path.funnelId
          audienceId: path.audienceId
      - text: Get funnel {funnelId} (parent segment {audienceId}) stats from {from} to {to}.
        slots:
          funnelId: path.funnelId
          audienceId: path.audienceId
          from: query.from
          to: query.to
      method: generated
      generated: '2026-09-26'
- target: $.paths['/entities/funnels'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a funnel via the entities API
      effect: write
      questions:
      - Can I create a funnel in the current Audience Studio without a parent segment path?
      - What attributes define a funnel created through the entities API?
      instructions:
      - text: Create an entities-API funnel with attributes {attributes}.
        slots:
          attributes: requestBody.attributes
      - text: Create a funnel with attributes {attributes} linked to {relationships}.
        slots:
          attributes: requestBody.attributes
          relationships: requestBody.relationships
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/funnels/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a funnel by entity ID
      effect: read
      questions:
      - Can I fetch a funnel using only its entity ID?
      - What does the entities API return for one funnel?
      instructions:
      - text: Get entities-API funnel {id}.
        slots:
          id: path.id
      - text: Fetch funnel entity {id} by its ID alone.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/funnels/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a funnel via the entities API
      effect: destructive
      questions:
      - Can I delete a funnel by its entity ID in the current Audience Studio?
      - What removes a funnel through the entities API?
      instructions:
      - text: Delete entities-API funnel {id}.
        slots:
          id: path.id
      - text: Remove funnel entity {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/funnels/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a funnel via the entities API
      effect: write
      questions:
      - Can I patch a funnel's attributes using only its entity ID?
      - Which funnel fields can the entities API update?
      instructions:
      - text: Patch entities-API funnel {id} with attributes {attributes}.
        slots:
          id: path.id
          attributes: requestBody.attributes
      - text: Update funnel entity {id} to {attributes}.
        slots:
          id: path.id
          attributes: requestBody.attributes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/funnels/{funnelId}/stages/{id}/statistics'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a funnel stage's population history
      effect: read
      questions:
      - How many profiles sat in one particular funnel stage each day?
      - Can I limit a funnel stage's population history to a date range?
      instructions:
      - text: Show daily population of stage {id} in funnel {funnelId}.
        slots:
          id: path.id
          funnelId: path.funnelId
      - text: Get population history of stage {id} in funnel {funnelId} from {from} to {to}.
        slots:
          id: path.id
          funnelId: path.funnelId
          from: query.from
          to: query.to
      method: generated
      generated: '2026-10-01'
- target: $.paths['/entities/parent_segments/{parentSegmentId}/funnels'].get
  update:
    x-apievangelist-phrasing:
      intent: List funnels by parent segment (entities API)
      effect: read
      questions:
      - Can I list funnels for a parent segment through the entities API?
      - Which funnel entities belong to a given parent segment?
      instructions:
      - text: List entities-API funnels for parent segment {parentSegmentId}.
        slots:
          parentSegmentId: path.parentSegmentId
      - text: Show funnel entities under parent segment {parentSegmentId}.
        slots:
          parentSegmentId: path.parentSegmentId
      method: generated
      generated: '2026-10-01'